fauna Query API

openapi: 3.1.0
info:
  title: Fauna Core HTTP EventFeeds Query API
  description: The Fauna Core HTTP API provides direct access to the Fauna serverless document database through HTTPS endpoints. It allows developers to execute Fauna Query Language (FQL) queries, manage databases, perform CRUD operations on documents, manage schema as FSL files, and consume change data capture events via event feeds. The API uses token-based authentication and supports features such as transactions, indexes, and set operations. It serves as the foundation upon which Fauna's client drivers and SDKs are built.
  version: '1'
  contact:
    name: Fauna Support
    url: https://support.fauna.com
  termsOfService: https://fauna.com/terms
servers:
- url: https://db.fauna.com
  description: Fauna Global Production Server
security:
- bearerAuth: []
tags:
- name: Query
  description: Execute Fauna Query Language (FQL) queries against a Fauna database.
paths:
  /query/1:
    post:
      operationId: executeQuery
      summary: Execute an FQL query
      description: Executes a Fauna Query Language (FQL) v10 query against the authenticated database. Each query is an independently authenticated request. The request body contains the FQL query string and optional arguments. The response includes the query result data, transaction timestamp, and operational statistics.
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/XFormat'
      - $ref: '#/components/parameters/XTypecheck'
      - $ref: '#/components/parameters/XLinearized'
      - $ref: '#/components/parameters/XQueryTimeout'
      - $ref: '#/components/parameters/XLastTxnTs'
      - $ref: '#/components/parameters/XQueryTags'
      - $ref: '#/components/parameters/XTraceparent'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '400':
          description: Bad request due to malformed query or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized due to invalid or missing authentication secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden due to insufficient privileges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict due to contention on the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          headers:
            X-Rate-Limited-Ops:
              description: Operations that were rate limited
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '440':
          description: Query timeout exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    XTypecheck:
      name: X-Typecheck
      in: header
      description: If true, enables type checking for the query. Fauna validates the query against the database schema before executing.
      schema:
        type: boolean
    XTraceparent:
      name: traceparent
      in: header
      description: W3C Trace Context traceparent header for distributed tracing.
      schema:
        type: string
    XQueryTags:
      name: X-Query-Tags
      in: header
      description: Arbitrary tags to associate with the query for logging and monitoring. Format is key=value pairs separated by commas.
      schema:
        type: string
    XLinearized:
      name: X-Linearized
      in: header
      description: If true, enforces strict serializability by ensuring reads reflect all prior committed transactions.
      schema:
        type: boolean
    XQueryTimeout:
      name: X-Query-Timeout-Ms
      in: header
      description: Query timeout in milliseconds. If the query exceeds this time, Fauna returns a 440 timeout error.
      schema:
        type: integer
        minimum: 1
    XLastTxnTs:
      name: X-Last-Txn-Ts
      in: header
      description: Last known transaction timestamp in microseconds since the Unix epoch. Used for snapshot isolation to ensure reads are at least as recent as this timestamp.
      schema:
        type: integer
        format: int64
    XFormat:
      name: X-Format
      in: header
      description: Specifies the data format used to encode FQL values in query results and arguments. Supported values are tagged and simple.
      schema:
        type: string
        enum:
        - tagged
        - simple
  schemas:
    QueryResponse:
      type: object
      properties:
        data:
          description: The query result data. The structure depends on the query executed and the X-Format header.
        static_type:
          type: string
          description: The static type of the query result as determined by Fauna's type system.
        txn_ts:
          type: integer
          format: int64
          description: Transaction timestamp in microseconds since the Unix epoch.
        stats:
          $ref: '#/components/schemas/QueryStats'
        schema_version:
          type: integer
          format: int64
          description: The schema version at the time the query was executed.
        summary:
          type: string
          description: Optional summary information about the query execution.
        query_tags:
          type: string
          description: Tags associated with the query for logging and monitoring.
    QueryRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: The FQL v10 query string to execute.
        arguments:
          type: object
          additionalProperties: true
          description: Optional named arguments to pass to the query. Arguments are available as variables in the FQL query.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code. Error codes are part of the API contract and are safe to write programmatic logic against.
            message:
              type: string
              description: Human-readable error message describing the failure.
            constraint_failures:
              type: array
              items:
                type: object
                properties:
                  paths:
                    type: array
                    items:
                      type: array
                      items:
                        type: string
                  message:
                    type: string
              description: Details about check or unique constraint failures.
          required:
          - code
          - message
        summary:
          type: string
          description: Detailed error information including the location of the error in the query.
        txn_ts:
          type: integer
          format: int64
          description: Transaction timestamp of the failed request.
        stats:
          $ref: '#/components/schemas/QueryStats'
        schema_version:
          type: integer
          format: int64
          description: Schema version at the time of the failed request.
    QueryStats:
      type: object
      description: Operational statistics for the query execution.
      properties:
        compute_ops:
          type: integer
          description: Number of Transactional Compute Operations consumed.
        read_ops:
          type: integer
          description: Number of Transactional Read Operations consumed.
        write_ops:
          type: integer
          description: Number of Transactional Write Operations consumed.
        query_time_ms:
          type: integer
          description: Query execution time in milliseconds.
        contention_retries:
          type: integer
          description: Number of times the transaction was retried due to contention.
        storage_bytes_read:
          type: integer
          description: Number of bytes read from storage.
        storage_bytes_write:
          type: integer
          description: Number of bytes written to storage.
        rate_limits_hit:
          type: array
          items:
            type: string
          description: List of rate limits that were hit during query execution.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Fauna authentication secret passed as a bearer token. Secrets can be keys, tokens, or JWTs from third-party identity providers.
externalDocs:
  description: Fauna Core HTTP API Documentation
  url: https://docs.fauna.com/fauna/current/reference/http/reference/core-api/