Convex Queries API

openapi: 3.2.0
info:
  title: Convex HTTP Queries API
  description: The Convex HTTP API is a REST interface for executing backend functions deployed on a Convex backend. It provides endpoints for invoking query, mutation, and action functions using POST requests. Each deployment has its own base URL found in the Convex dashboard settings, typically in the format https://{deployment-name}.convex.cloud. Requests accept a function path and named argument object as JSON, and responses include the function return value along with execution log lines. User authentication is optional via a bearer token from an auth provider; admin operations require a deploy key using the Convex authorization scheme.
  version: '1.0'
  contact:
    name: Convex Support
    url: https://www.convex.dev/community
  termsOfService: https://www.convex.dev/terms
servers:
- url: https://{deploymentName}.convex.cloud
  description: Convex Deployment Server
  variables:
    deploymentName:
      default: happy-otter-123
      description: The deployment name from the Convex dashboard
security:
- bearerAuth: []
tags:
- name: Queries
  description: Execute read-only query functions deployed on the Convex backend. Queries run in a transactional, reactive context and return data from the Convex database.
paths:
  /api/query:
    post:
      operationId: executeQuery
      summary: Execute a query function
      description: Executes a read-only query function deployed on the Convex backend. The function is identified by its module path and export name (e.g. "myModule:myQuery"). Named arguments are passed as a JSON object. Returns the function's return value and any console log output produced during execution.
      tags:
      - Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunctionRequest'
      responses:
        '200':
          description: Function executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionSuccessResponse'
        '400':
          description: Bad request — invalid function path or argument format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionErrorResponse'
        '401':
          description: Unauthorized — missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionErrorResponse'
        '404':
          description: Function not found at the given path
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionErrorResponse'
components:
  schemas:
    FunctionSuccessResponse:
      type: object
      required:
      - status
      - value
      - logLines
      properties:
        status:
          type: string
          description: Indicates the function executed without error.
          enum:
          - success
        value:
          description: The return value of the function. The type depends on the function's return type definition and may be any valid JSON value including objects, arrays, strings, numbers, booleans, or null.
        logLines:
          type: array
          description: An array of strings representing console output (e.g. console.log) produced by the function during execution.
          items:
            type: string
    FunctionRequest:
      type: object
      required:
      - path
      - args
      properties:
        path:
          type: string
          description: The fully-qualified function path in the format "module:functionName" (e.g. "messages:list"). The module name maps to the file path within the convex/ directory.
          pattern: ^[a-zA-Z0-9_/]+:[a-zA-Z0-9_]+$
          example: messages:list
        args:
          type: object
          description: Named arguments to pass to the function as a JSON object. The keys and value types must match the function's declared parameter types.
          additionalProperties: true
        format:
          type: string
          description: Output format for the response value. Currently only "json" is supported and is also the default when omitted.
          enum:
          - json
          default: json
    FunctionErrorResponse:
      type: object
      required:
      - status
      - errorMessage
      - logLines
      properties:
        status:
          type: string
          description: Indicates the function encountered an error during execution.
          enum:
          - error
        errorMessage:
          type: string
          description: A human-readable description of the error that occurred during function execution.
        errorData:
          type: object
          description: Additional structured data about the error, present when the function throws a ConvexError with associated data. The shape depends on the application-specific error definition.
          additionalProperties: true
        logLines:
          type: array
          description: An array of strings representing console output produced by the function prior to the error.
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token from the application's configured authentication provider (e.g. Auth0, Clerk). Used for user-level authorization of function calls.
    convexAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Deploy key obtained from the Convex dashboard, formatted as "Convex {deployKey}". Required for admin-level operations and streaming endpoints.
externalDocs:
  description: Convex HTTP API Documentation
  url: https://docs.convex.dev/http-api/