fauna EventFeeds API

openapi: 3.2.0
info:
  title: Fauna Core HTTP Event Feeds API
  description: The Fauna Core HTTP API provides direct access to the Fauna serverless document database through HTTPS endpoints.
  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: EventFeeds
  description: Poll-based change data capture using event feeds. Retrieve batches of change events at your own pace for scheduled synchronization and batch processing workflows.
paths:
  /feed/1:
    post:
      operationId: pollEventFeed
      summary: Poll an event feed
      description: Retrieves a page of change data capture events from an event source using a polling-based approach. Event feeds allow developers to retrieve batches of change events at their own pace rather than maintaining a persistent connection. Specify a start timestamp for the initial request and use cursors for subsequent pagination.
      tags:
      - EventFeeds
      parameters:
      - $ref: '#/components/parameters/XFormat'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventFeedRequest'
      responses:
        '200':
          description: Event feed page retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventFeedResponse'
        '400':
          description: Bad request due to invalid token or 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'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Event:
      type: object
      properties:
        type:
          type: string
          enum:
          - add
          - remove
          - update
          - status
          description: The type of change event.
        txn_ts:
          type: integer
          format: int64
          description: Transaction timestamp of the event in microseconds since the Unix epoch.
        cursor:
          type: string
          description: Cursor for this specific event.
        data:
          type: object
          additionalProperties: true
          description: The document data associated with the event.
    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.
    EventFeedResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: Array of change events for the current page.
        cursor:
          type: string
          description: Cursor to use for fetching the next page of events.
        has_next:
          type: boolean
          description: Indicates whether more pages of events are available.
        stats:
          $ref: '#/components/schemas/EventStats'
    EventStats:
      type: object
      description: Aggregated statistics for all events in the page.
      properties:
        read_ops:
          type: integer
          description: Number of Transactional Read Operations consumed.
        storage_bytes_read:
          type: integer
          description: Number of bytes read from storage.
        compute_ops:
          type: integer
          description: Number of Transactional Compute Operations consumed.
        processing_time_ms:
          type: integer
          description: Processing time in milliseconds.
        rate_limits_hit:
          type: array
          items:
            type: string
          description: List of rate limits that were hit.
    EventFeedRequest:
      type: object
      required:
      - token
      properties:
        token:
          type: string
          description: The event source token obtained from an FQL query that returns an event source.
        cursor:
          type: string
          description: Cursor from a previous event feed response for pagination. Mutually exclusive with start_ts.
        start_ts:
          type: integer
          format: int64
          description: Start timestamp in microseconds since the Unix epoch. Fauna returns events that occurred after this timestamp. Mutually exclusive with cursor.
        page_size:
          type: integer
          minimum: 1
          maximum: 16000
          default: 16
          description: Maximum number of events to return per page. Must be between 1 and 16000 inclusive.
    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.
  parameters:
    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
  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/