canonical: https://jentic.com/apis/convexdev/convex # Convexdev Convex HTTP API This page describes a curated, agent-optimized Jentic specification of the Convex HTTP API, kept validated and agent-ready. Convex ships an official OpenAPI generator in its convex-helpers package, and that generator emits a YAML file for the functions of one specific deployment rather than a single hosted document for the shared HTTP surface, so Jentic maintains this spec of the surface itself. The Convex HTTP API lets external clients invoke query, mutation, and action functions defined on a Convex deployment without using the Convex SDK. Functions are addressed either by category-specific endpoints (`/api/query`, `/api/mutation`, `/api/action`) or by arbitrary path through `/api/run/{functionIdentifier}.` Authentication accepts either a deployment Bearer token or the 'Convex {access_key}' admin key in the Authorization header. ## For AI agents Invoke Convex query, mutation, and action functions on a deployment from any HTTP client. Agents authenticate with a deployment Bearer token or Convex admin key. ## Scope Does not deploy code, manage schemas, or stream subscriptions - use for invoking deployed Convex query, mutation, and action functions over HTTP only. ## Capabilities - Call a Convex query function and read deployment data via POST `/api/query` - Run a Convex mutation function to write or update records via POST `/api/mutation` - Trigger a Convex action function for external side effects via POST `/api/action` - Invoke any Convex function by path with POST `/api/run/{functionIdentifier}` - Authenticate with a deployment Bearer token or the 'Convex {access_key}' admin format ## Use cases ### External Service Calls Into Convex Let an external backend (Node, Python, Go) read or mutate Convex deployment state without bundling the Convex SDK. POST `/api/query` and `/api/mutation` accept the function name and arguments and return the result, so existing services can integrate Convex over plain HTTP. Suited to teams running Convex alongside legacy backends that already speak REST. Example prompt: POST `/api/query` with path 'messages:list' and arguments {channelId: 'general'} and return the result ### Cron-Triggered Convex Mutations Wire a scheduler such as cron-job.org or a CI cron to POST a Convex mutation on a recurring schedule, for example to expire stale records or refresh aggregates. The single POST `/api/mutation` call slots into any HTTP scheduler and the function runs inside the deployment. Useful when scheduled work needs to live in Convex code but be triggered externally. Example prompt: Call POST `/api/mutation` with function 'cleanup:expireRecords' every hour and log the result ### Webhook Endpoints That Run Convex Actions Have an upstream system (Stripe, GitHub, Sentry) post webhooks to a thin proxy that forwards them to `/api/action` on a Convex deployment. Actions can perform side effects (email, third-party calls) as part of the deployment logic. Useful when teams want webhook handling colocated with their Convex code rather than living in a separate function service. Example prompt: On a Stripe payment_succeeded webhook, POST `/api/action` with function 'payments:onSucceeded' and the event payload ### Agent-Driven Convex Operations via Jentic An AI agent calls Convex query, mutation, and action functions through Jentic without holding the deployment key. The agent searches Jentic for a function intent, loads the schema, and executes the appropriate POST. Through Jentic the deployment Bearer or admin key is injected from the vault so agent automation runs without secret exposure. Example prompt: Search Jentic for 'call a convex function', load the schema, then run the messages:list query and return results ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/api/query` | Call a Convex query function | | POST | `/api/mutation` | Call a Convex mutation function | | POST | `/api/action` | Call a Convex action function | | POST | `/api/run/{functionIdentifier}` | Call any Convex function by identifier | ## Key resources - **Query** — Read-only Convex functions invoked via POST `/api/query` - **Mutation** — State-changing Convex functions invoked via POST `/api/mutation` - **Action** — Side-effect Convex functions (external calls) invoked via POST `/api/action` - **Run** — Generic dispatch endpoint that accepts any function identifier ## Why Jentic - **Setup:** Wiring Convex by hand means resolving your per-deployment {deployment}.convex.cloud host, choosing bearer or admin-key auth, and shaping the query, mutation, and action calls yourself. Through Jentic you install once, import the Convex HTTP API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** The Convex function to invoke is named in the request, so scope this by operations: allow the agent the calls it needs, such as running queries and actions, and leave out mutation if you want it read-only. Each operation you credit the agent with stays inside that allowed set. - **Credential handling:** Your Convex deployment token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'call a Convex query function' or 'run a Convex mutation', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Hasura API** — GraphQL backend that auto-generates an API over a Postgres database, similar full-stack scope. - **Appwrite Server API** — Self-hostable backend with database, auth, and functions, similar developer scope to Convex. - **Neon API** — Serverless Postgres that pairs with Convex when relational storage is needed alongside Convex functions. ## FAQ ### Which OpenAPI specification does this Convex HTTP API page describe? A curated, agent-optimized Jentic specification covering the 4 Convex HTTP API operations: the query, mutation, action, and generic run calls. Convex also ships its own OpenAPI generator in the convex-helpers package: running `npx convex-helpers open-api-spec` inside a Convex folder writes a `convex-spec-{msSinceEpoch}.yaml` file describing the functions of that one deployment, and the documentation for it sits at https://github.com/get-convex/convex-helpers/blob/main/packages/convex-helpers/README.md#open-api-spec-generation. Because that output is generated per deployment rather than hosted as one document, the Jentic variant describes the stable HTTP surface every deployment shares, so an agent can call it without first generating a spec. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Convex HTTP API use? Two schemes are supported: HTTP Bearer with a deployment access token in the Authorization header, and the apiKey scheme using 'Convex {access_key}' (admin key) also in the Authorization header. Through Jentic both options are stored in the vault and injected at execution time so they never enter the agent's prompt. ### How do I call a Convex query function over HTTP? POST to `/api/query` with a JSON body containing the function path (e.g. 'messages:list') and an args object. The deployment runs the function and returns the result inline. Use `/api/mutation` for write operations and `/api/action` for side-effect functions. ### Can I call any Convex function with a single endpoint? Yes. POST `/api/run/{functionIdentifier}` dispatches to whichever query, mutation, or action lives at the supplied identifier. This is useful when the caller does not statically know which function category will be invoked. ### What is the base URL for the Convex HTTP API? Each Convex deployment has its own URL of the form https://{deployment}.convex.cloud. Substitute your deployment identifier (e.g. happy-fox-123) for {deployment} when making calls. ### How do I invoke a Convex function through Jentic? Run jentic search for 'call a convex function', load the POST `/api/query`, `/api/mutation`, `/api/action`, or `/api/run` operation, then execute it with the function path and arguments. Jentic injects the deployment Bearer or admin key from the vault and returns the function output. ### What are the rate limits for the Convex HTTP API? Rate limits depend on the deployment plan and are not declared in the OpenAPI spec. Treat the function endpoints as soft-limited per deployment and back off on HTTP 429 responses. Consult Convex's pricing page for plan-level concurrency and request limits. ### Can I limit what my agent is allowed to do with the Convex HTTP API? Yes. Because Jentic One is self-hosted, your own rules decide which Convex operations the agent may call, and it is scoped per operation. You can allow the read-only query call (POST `/api/query`) and the side-effect action call (POST `/api/action`) while leaving out the mutation call (POST `/api/mutation`) to keep the agent from writing data, and you can withhold the generic POST `/api/run` dispatch so it cannot reach functions you did not credit. The agent can only invoke the operations you grant, and your deployment token stays with your instance rather than the agent's prompt.