ActionCtx
Handler receives ActionCtx with auth, storage, scheduler, runQuery, runMutation, runAction.
Actions
Unrestricted functions that can call third-party HTTP endpoints via fetch.
agents
auth
Request/response body types
Supports .text(), .json(), .blob(), and .arrayBuffer() body types.
components
Convex Documentation
.convex.site domain
HTTP actions are exposed at https://<deployment name>.convex.site.
Cron jobs
Internal functions can be scheduled to run periodically from cron jobs.
Dashboard and CLI
Internal functions can be run using the Dashboard or from the CLI.
database
Default Convex runtime
Custom V8-based JavaScript runtime similar to Cloudflare Workers, always on.
file-storage
functions
Future scheduling
Helper functions
Split or reuse logic via helper functions, also accepting QueryCtx.
HTTP Actions
Call your functions from a webhook or a custom client.
httpPrefix routing
Namespace routes under a path prefix via httpPrefix in convex.config.ts.
httpAction constructor
Define HTTP action handlers with the httpAction constructor.
HttpRouter
Export an HttpRouter instance from convex/http.ts and expose routes with route().
Internal Action
Defined with internalAction; callable only from other functions, not from a Convex client.
Internal functions
Internal queries and mutations prevent users from calling them directly from clients.
Internal Mutation
Defined with internalMutation; callable only from other functions, not from a Convex client.
Internal Query
Defined with internalQuery; callable only from other functions, not from a Convex client.
Mutation constructor
Declare mutations with the mutation constructor and a handler function.
Mutation context
MutationCtx exposes db, storage, auth and scheduler fields.
Mutations
Write data to the database and run as a transaction.
Named arguments
Queries accept named arguments accessible on the handler's second parameter.
Node.js runtime
Opt-in runtime enabled with the "use node" directive for libraries needing Node features.
NPM packages
Queries can import NPM packages installed in node_modules, with runtime caveats.
Queries
Read data from the Convex database; cached, subscribable, transactional, real-time.
query constructor
Declares a query by passing an object with a handler function that returns the result.
Query context
QueryCtx provides db, storage and auth fields to the handler.
Query names
File path and export name determine the client-callable name, e.g. "myFunctions:myQuery".
realtime
Record Objects
Describe objects mapping arbitrary keys to values with v.record.
runAction
HTTP actions can call internal functions via runAction.
runQuery and runMutation
Actions and HTTP actions call internal functions via runQuery and runMutation.
scheduling
search
Seeded randomness
Math.random() is seeded to guarantee determinism in queries and mutations.
Supported Types
Public and internal functions accept and return supported Convex value types.
testing
understanding
Unions and Literals
Express multi-type fields with v.union and constants with v.literal.
useMutation hook
Call mutations from React with the useMutation hook and generated api object.
"use node" directive
Add at top of file to run actions in Node.js instead of Convex's JavaScript environment.
useAction hook
Call an action from React using the useAction hook with the generated api object.
useQuery hook
React hook used with the generated api object to call queries from clients.
Validators
Add args and returns validators to query, mutation, or action constructors.