fauna Schema API

openapi: 3.1.0
info:
  title: Fauna Core HTTP EventFeeds Schema 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: Schema
  description: Fetch, update, validate, and manage a database's schema as FSL files. Supports staged schema changes with status checking, committing, and abandoning.
paths:
  /schema/1/files:
    get:
      operationId: getSchemaFiles
      summary: Get schema files
      description: Retrieves the FSL schema files for the authenticated database. Returns the active schema files or staged schema files if a staged schema change is in progress. Requires an authentication secret with the built-in admin, server, or server-readonly role.
      tags:
      - Schema
      parameters:
      - name: staged
        in: query
        description: If true, return staged schema files instead of active schema files.
        schema:
          type: boolean
          default: false
      - name: version
        in: query
        description: Schema version timestamp to retrieve a specific version of the schema files.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Schema files retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaFilesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden due to insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /schema/1/update:
    post:
      operationId: updateSchemaFiles
      summary: Update schema files
      description: Updates the FSL schema files for the authenticated database. You can push schema changes as staged changes or apply them immediately. Each form-data field corresponds to a file name and contains the FSL file content. A database can have up to 1024 FSL files. Requires an authentication secret with the built-in admin role.
      tags:
      - Schema
      parameters:
      - name: staged
        in: query
        description: If true, stage the schema changes instead of applying immediately.
        schema:
          type: boolean
          default: false
      - name: version
        in: query
        description: Expected schema version. The request fails if the version does not match the current schema version.
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties:
                type: string
                description: FSL file content. The field name is the file name including any relative path.
      responses:
        '200':
          description: Schema updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaUpdateResponse'
        '400':
          description: Schema validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden due to insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Schema version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /schema/1/validate:
    post:
      operationId: validateSchemaFiles
      summary: Validate schema files
      description: Validates the provided FSL schema files against the current schema without applying any changes. Returns a diff between the proposed and current schema. Useful for previewing changes before pushing.
      tags:
      - Schema
      parameters:
      - name: staged
        in: query
        description: If true, validate against staged schema instead of active schema.
        schema:
          type: boolean
          default: false
      - name: version
        in: query
        description: Expected schema version for validation.
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties:
                type: string
                description: FSL file content to validate.
      responses:
        '200':
          description: Validation result with diff
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaValidationResponse'
        '400':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /schema/1/status:
    get:
      operationId: getStagedSchemaStatus
      summary: Get staged schema status
      description: Gets the index build status for the database's current staged schema. You can only commit staged schema with a status of ready. If format is specified, the request also returns a diff between the staged and active schema. Requires an authentication secret with the built-in admin, server, or server-readonly role.
      tags:
      - Schema
      parameters:
      - name: version
        in: query
        description: Expected schema version.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Staged schema status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaStatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /schema/1/staged/commit:
    post:
      operationId: commitStagedSchema
      summary: Commit staged schema
      description: Applies the currently staged schema change to the database. You can only commit a staged schema that has a status of ready. This is the API equivalent of the fauna schema commit CLI command.
      tags:
      - Schema
      parameters:
      - name: version
        in: query
        description: Expected schema version.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Staged schema committed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaCommitResponse'
        '400':
          description: Cannot commit schema that is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /schema/1/staged/abandon:
    post:
      operationId: abandonStagedSchema
      summary: Abandon staged schema
      description: Discards the currently staged schema change. You can abandon a staged schema change at any time including changes with a ready status. This is the API equivalent of the fauna schema abandon CLI command.
      tags:
      - Schema
      parameters:
      - name: version
        in: query
        description: Expected schema version.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Staged schema abandoned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaAbandonResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /import:
    post:
      operationId: importGraphQLSchema
      summary: Import a GraphQL schema
      description: Imports a GraphQL schema definition into the authenticated Fauna database. Fauna automatically creates collections, indexes, and resolvers based on the schema types and relationships. Use mode parameter to control whether to merge with or replace the existing schema.
      tags:
      - Schema
      parameters:
      - name: mode
        in: query
        description: Schema import mode. Use merge to add to the existing schema or replace to overwrite it entirely. Override allows updating existing types.
        schema:
          type: string
          enum:
          - merge
          - replace
          - override
          default: merge
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: GraphQL schema definition language (SDL) content.
          multipart/form-data:
            schema:
              type: object
              properties:
                schema:
                  type: string
                  format: binary
                  description: GraphQL schema file to import.
      responses:
        '200':
          description: Schema imported successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message indicating the schema was imported.
        '400':
          description: Invalid GraphQL schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLErrorResponse'
components:
  schemas:
    SchemaFile:
      type: object
      properties:
        filename:
          type: string
          description: Name of the FSL file including any relative path.
        content:
          type: string
          description: Contents of the FSL schema file.
    GraphQLErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GraphQLError'
          description: Array of errors that prevented query execution.
    SchemaAbandonResponse:
      type: object
      properties:
        version:
          type: integer
          format: int64
          description: Active schema version after abandoning the staged change.
    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.
    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.
    SchemaCommitResponse:
      type: object
      properties:
        version:
          type: integer
          format: int64
          description: New active schema version after committing.
    SchemaFilesResponse:
      type: object
      properties:
        version:
          type: integer
          format: int64
          description: Schema version timestamp.
        files:
          type: array
          items:
            $ref: '#/components/schemas/SchemaFile'
          description: Array of FSL schema files.
    SchemaValidationResponse:
      type: object
      properties:
        version:
          type: integer
          format: int64
          description: Current schema version.
        diff:
          type: string
          description: Diff between the proposed and current schema.
        valid:
          type: boolean
          description: Whether the proposed schema is valid.
    SchemaUpdateResponse:
      type: object
      properties:
        version:
          type: integer
          format: int64
          description: New schema version timestamp after the update.
        diff:
          type: string
          description: Diff between the previous and updated schema.
    SchemaStatusResponse:
      type: object
      properties:
        version:
          type: integer
          format: int64
          description: Schema version timestamp.
        status:
          type: string
          enum:
          - none
          - pending
          - ready
          - failed
          description: Index build status for the staged schema. Only schemas with a ready status can be committed.
        diff:
          type: string
          description: Diff between the staged and active schema if format was specified.
    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/