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:
- Shell
- NodeJS
- Python
curl https://acoustic-panther-728.convex.cloud/api/query \
-d '{"path": "messages:list", "args": {}, "format": "json"}' \
-H "Content-Type: application/json"
const url = "https://acoustic-panther-728.convex.cloud/api/query";
const request = { path: "messages:list", args: {}, format: "json" };
const response = fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(request),
});
import requests
url = "https://acoustic-panther-728.convex.cloud/api/query"
headers = {"accept": "application/json"}
body = {"path": "messages:list", "args": {}, "format": "json"}
response = requests.post(url, headers=headers, json=body)
JSON Body parameters
Name | Type | Required | Description |
---|---|---|---|
path | string | y | Path to the Convex function formatted as a string as defined here. |
args | object | y | Named argument object to pass to the Convex function. |
format | string | n | Output format for values. Valid values: [json ] |
Result JSON on success
Field Name | Type | Description |
---|---|---|
status | string | "success" |
value | object | Result of the Convex function in the requested format. |
logLines | list[string] | Log lines printed out during the function execution. |
Result JSON on error
Field Name | Type | Description |
---|---|---|
status | string | "error" |
errorMessage | string | The error message. |
errorData | object | Error data within an application error if it was thrown. |
logLines | list[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:
- Shell
- NodeJS
- Python
curl https://acoustic-panther-728.convex.cloud/api/run/messages/list \
-d '{"args": {}, "format": "json"}' \
-H "Content-Type: application/json"
const url = "https://acoustic-panther-728.convex.cloud/api/run/messages/list";
const request = { args: {}, format: "json" };
const response = fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(request),
});
import requests
url = "https://acoustic-panther-728.convex.cloud/api/run/messages/list"
headers = {"accept": "application/json"}
body = {"args": {}, "format": "json"}
response = requests.get(url, headers=headers, body=json)
JSON Body parameters
Name | Type | Required | Description |
---|---|---|---|
args | object | y | Named argument object to pass to the Convex function. |
format | string | n | Output format for values. Defaults to json . Valid values: [json ] |
Result JSON on success
Field Name | Type | Description |
---|---|---|
status | string | "success" |
value | object | Result of the Convex function in the requested format. |
logLines | list[string] | Log lines printed out during the function execution. |
Result JSON on error
Field Name | Type | Description |
---|---|---|
status | string | "error" |
errorMessage | string | The error message. |
errorData | object | Error data within an application error if it was thrown. |
logLines | list[string] | Log lines printed out during the function execution. |