Skip to main content

Convex HTTP API

The public functions that define a deployment are exposed at public HTTP endpoints.

Convex value format

Each of the HTTP APIs take a format query param that describes how documents are formatted. Currently the only supported value is json. See our types page for details. Note that for simplicity, the json format does not support all Convex data types as input, and uses overlapping representation for several data types in output. We plan to add a new format with support for all Convex data types in the future.

API authentication

The Functions API can be optionally authenticated as a user via a bearer token in a Authorization header. The value is Bearer <access_key> where the key is a token from your auth provider. See the under the hood portion of the Clerk docs for details on how this works with Clerk.

Streaming export and streaming import requests require deployment admin authorization via the HTTP header Authorization. The value is Convex <access_key> where the access key comes from "Deploy key" on the Convex dashboard and gives full read and write access to your Convex data.

Functions API

POST /api/query, /api/mutation, /api/action

These HTTP endpoints allow you to call Convex functions and get the result as a value.

You can find your backend deployment URL on the dashboard Settings page, then the API URL will be <CONVEX_URL>/api/query etc., for example:

curl https://acoustic-panther-728.convex.cloud/api/query \
-d '{"path": "messages:list", "args": {}, "format": "json"}' \
-H "Content-Type: application/json"

JSON Body parameters

NameTypeRequiredDescription
pathstringyPath to the Convex function formatted as a string as defined here.
argsobjectyNamed argument object to pass to the Convex function.
formatstringnOutput format for values. Valid values: [json]

Result JSON on success

Field NameTypeDescription
statusstring"success"
valueobjectResult of the Convex function in the requested format.
logLineslist[string]Log lines printed out during the function execution.

Result JSON on error

Field NameTypeDescription
statusstring"error"
errorMessagestringThe error message.
errorDataobjectError data within an application error if it was thrown.
logLineslist[string]Log lines printed out during the function execution.

POST /api/run/{functionIdentifier}

This HTTP endpoint allows you to call arbitrary Convex function types with the path in the request URL and get the result as a value. The function identifier is formatted as a string as defined here with a / replacing the :.

You can find your backend deployment URL on the dashboard Settings page, then the API URL will be <CONVEX_URL>/api/run/{functionIdentifier} etc., for example:

curl https://acoustic-panther-728.convex.cloud/api/run/messages/list \
-d '{"args": {}, "format": "json"}' \
-H "Content-Type: application/json"

JSON Body parameters

NameTypeRequiredDescription
argsobjectyNamed argument object to pass to the Convex function.
formatstringnOutput format for values. Defaults to json. Valid values: [json]

Result JSON on success

Field NameTypeDescription
statusstring"success"
valueobjectResult of the Convex function in the requested format.
logLineslist[string]Log lines printed out during the function execution.

Result JSON on error

Field NameTypeDescription
statusstring"error"
errorMessagestringThe error message.
errorDataobjectError data within an application error if it was thrown.
logLineslist[string]Log lines printed out during the function execution.