Fauna GraphQL API

openapi: 3.2.0
info:
  title: Fauna Core HTTP EventFeeds Graph QL 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: GraphQL
  description: Execute GraphQL queries and mutations against a Fauna database.
paths:
  /graphql:
    post:
      operationId: executeGraphQLQuery
      summary: Execute a GraphQL query or mutation
      description: Executes a GraphQL query or mutation against the authenticated Fauna database. The database must have a GraphQL schema imported. Fauna automatically resolves queries and mutations based on the imported schema, creating the necessary collections and indexes. Supports standard GraphQL features including variables and operation names.
      tags:
      - GraphQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
          application/graphql:
            schema:
              type: string
              description: Raw GraphQL query string when using application/graphql content type.
      responses:
        '200':
          description: GraphQL query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '400':
          description: Bad request due to malformed GraphQL query or syntax error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLErrorResponse'
        '401':
          description: Unauthorized due to invalid or missing authentication secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLErrorResponse'
components:
  schemas:
    GraphQLRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation string.
        variables:
          type: object
          additionalProperties: true
          description: Variables to pass to the GraphQL query or mutation.
        operationName:
          type: string
          description: The name of the operation to execute if the query document contains multiple operations.
    GraphQLErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GraphQLError'
          description: Array of errors that prevented query execution.
    GraphQLError:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        locations:
          type: array
          items:
            type: object
            properties:
              line:
                type: integer
                description: Line number in the query where the error occurred.
              column:
                type: integer
                description: Column number in the query where the error occurred.
          description: Locations in the query document where the error occurred.
        path:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
          description: Path to the field that caused the error in the response data.
        extensions:
          type: object
          additionalProperties: true
          description: Additional error information specific to Fauna.
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
          description: The query result data matching the shape of the GraphQL query.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GraphQLError'
          description: Array of errors encountered during query execution. May be present alongside data for partial success.
  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/