API docs by Redocly

Fauna Core API

Download OpenAPI specification:Download

You can use the Fauna Core HTTP API to:

The Fauna client drivers, Fauna Dashboard, and Fauna CLI use the Core API to access data in Fauna databases.

Base URL

Fauna Core API endpoints use https://db.fauna.com as the base URL.

For example, the full URL for the /query/1 (Query) endpoint is https://db.fauna.com/query/1.

Fauna routes requests to a database based on the secret used for authentication. All requests and queries run in the context of a single database.

Authentication

You authenticate requests to Fauna Core API endpoints using an authentication secret. You pass the authentication secret as a bearer token in the Authorization request header.

Get an authentication secret

Fauna supports several secret types. For testing, you can create a key, which is a type of secret:

  1. Log in to the Fauna Dashboard.

  2. On the Explorer page, create a database.

  3. In the database's Keys tab, click Create Key.

  4. Choose a Role of server.

  5. Click Save.

  6. Copy the Key Secret. The secret is scoped to the database.

Query

The Query endpoint lets you run Fauna Query Language (FQL) queries.

Query endpoint

Runs an FQL query against a specific database.

Every query is an independently authenticated request to the Query endpoint. The Fauna client drivers, Fauna Dashboard, and Fauna CLI use the Query endpoint to run queries.

In Fauna, every query is a transaction, run in the context of a single database. Fauna routes and authorizes queries using an authentication secret, scoped to a specific database. You pass the authentication secret as a bearer token in the Authorization request header.

Data format

The Query endpoint's X-Format request header specifies the data format used to encode FQL values in:

  • Query results.
  • FQL query arguments passed in the arguments parameter or within objects passed to the query parameter.
  • Abort values returned by abort errors.

See the Wire protocol docs.

Error handling

Error responses from the Query API include error codes.

Fauna error codes are part of the API contract and are safe to write programmatic logic against. You should first handle errors based on error code, rather than HTTP status code.

See Error handling.

Authorizations:
bearerAuth
header Parameters
Authorization
required
string
Example: Bearer <FAUNA_SECRET>

A Fauna authentication secret, passed as a bearer token.

See Authentication for more details.

X-Format
string

Data format used to encode FQL values as JSON (and the reverse) in:

  • Query results returned in the data property of successful responses.

  • FQL query arguments used to interpolate app variables into queries. Defines the arguments parameter or within objects passed to the query parameter.

  • Abort values returned by abort errors.

Accepts simple (default) and tagged.

For more information, see Wire Protocol.

X-Last-Txn-Ts
integer

If set, acts as the minimum snapshot time against which the query executes.

Fauna's client drivers set this value as the last txn_ts (transaction timestamp) value seen by the client in query responses.

X-Linearized
boolean

If true, strictly serializes read-only queries that don't involve indexes.

Queries that include writes are already strictly serialized.

See Strictly serialize read-only transactions.

X-Max-Contention-Retries
integer

Maximum number of times to retry the query due to transaction contention.

See Manage retries for contended transactions.

X-Query-Tags
string

A string-encoded set of query tags.

Query tags let you instrument queries to better identify their source and context in Fauna Logs. Query tags are returned in the response's query_tags property.

You provide query tags as a list of key=value pairs. For example:

  • foo=bar
  • foo=bar,baz=blah
  • foo_bar=baz
  • foo3=1234,5=6

Keys and values may only support [a-zA-Z0-9_] characters. The following are invalid query tags:

  • foo bar=3 // no spaces
  • foo=bar, // no trailing commas
  • foo==bar // too many =

Queries that include invalid tags return an invalid_request error code and a 400 HTTP status code.

A query can't include more than 25 query tags.

Each key must be less than or equal to 40 bytes. Each value must be less than or equal to 80 bytes. The full header can't exceed 3000 bytes.

X-Query-Timeout-Ms
integer

Maximum runtime for the request in milliseconds.

X-Typecheck
boolean

Enable or disable typechecking for the query.

Defaults to the typechecking configuration for the database.

Request Body schema: application/json
required
required
object or string

FQL query to run. Accepts an object or a string.

Use arguments to interpolate variables from your application into the query.

arguments
object

Object containing variables to interpolate into the query.

The key of each object property is the name of the variable, referenced in the query. The property value is the variable's value.

Variable names must be valid FQL identifiers. Variable values should be encoded using the data format specified in the X-Format request header.

Responses

Request samples

Content type
application/json
Example
{
  • "query": {
    • "fql": [
      • "Product.all().where(.stock ==",
      • {
        • "value": {
          • "@int": "10"
          }
        },
      • ")"
      ]
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "data": {
      • "id": "410212968961146957",
      • "coll": {
        • "@mod": "Product"
        },
      • "ts": {
        • "@time": "2099-07-29T14:26:37.650Z"
        },
      • "name": "cups",
      • "description": "Translucent 9 Oz, 100 ct",
      • "price": {
        • "@int": 698
        },
      • "stock": {
        • "@int": 100
        },
      • "category": {
        • "@ref": {
          • "id": "410212968956952653",
          • "coll": {
            • "@mod": "Category"
            }
          }
        }
      }
    },
  • "static_type": "Set<Product>",
  • "summary": "",
  • "txn_ts": 1727892962009660,
  • "stats": {
    • "compute_ops": 1,
    • "read_ops": 18,
    • "write_ops": 0,
    • "query_time_ms": 215,
    • "contention_retries": 0,
    • "storage_bytes_read": 2158,
    • "storage_bytes_write": 0,
    • "rate_limits_hit": [ ]
    },
  • "schema_version": 1727880352326000
}

Event

Event endpoints lets you consume events from an event source. An event source emits an event whenever tracked changes are made to a database.

You can consume the events in two ways:

  • Event Feeds: Make asynchronous requests that poll the event source for paginated events using the Event Feed endpoint.

  • Event Streams: Establish a real-time subscription that pushes events to your application through an open connection to the Event Stream endpoint.

Event Feed endpoint

The Event Feed endpoint is in beta. To use the Event Feed endpoint, you must have a Pro or Enterprise plan.

Asynchronously gets events from an event source as a paginated Event Feed.

Authorizations:
bearerAuth
header Parameters
Authorization
required
string
Example: Bearer <FAUNA_SECRET>

A Fauna authentication secret, passed as a bearer token.

See Authentication for more details.

X-Query-Timeout-Ms
integer

Maximum runtime for the request in milliseconds.

Request Body schema: application/json
required
token
required
string

Event source token.

The event source token determines:

  • The events returned in the Event Feed.
  • The default start_ts, which is the event source query's timestamp.
cursor
string

Cursor for a previous event. If provided, the event source replays any events that occurred after the cursor (exclusive).

You can reuse cursors across event sources with identical queries in the same database.

You can't pass both start_ts and cursor.

If you don't provide a cursor or start_ts, start_ts defaults to the transaction timestamp of the query that created the event source.

start_ts
integer

Stream start time in microseconds since the Unix epoch. This is typically a previous event's txn_ts (transaction timestamp).

You can't pass both start_ts and cursor.

If you don't provide a cursor or start_ts, start_ts defaults to the event source query's timestamp.

If start_ts is outside the history retention period of the source Set's collection, the feed returns an error event with the invalid_start_time error code.

page_size
integer

Maximum number of events returned per page.

Must be in the range 1 to 16000 (inclusive). Defaults to 16.

Responses

Request samples

Content type
application/json
{
  • "token": "<EVENT_SOURCE>",
  • "cursor": "gsGabc123",
  • "start_ts": 1710968002310000,
  • "page_size": 10
}

Response samples

Content type
application/json
Example
{
  • "events": [
    • {
      • "type": "update",
      • "data": {
        • "@doc": {
          • "id": "412095363338469409",
          • "coll": {
            • "@mod": "Product"
            },
          • "ts": {
            • "@time": "2099-10-18T21:54:07.340Z"
            },
          • "name": "cups",
          • "description": "Translucent 9 Oz, 100 ct",
          • "price": {
            • "@int": "698"
            },
          • "stock": {
            • "@int": "99"
            },
          • "category": {
            • "@ref": {
              • "id": "412095363334275105",
              • "coll": {
                • "@mod": "Category"
                }
              }
            }
          }
        },
      • "txn_ts": 1729288447340000,
      • "cursor": "gsGCGmcS2P8aFEP9AAA=",
      • "stats": {
        • "read_ops": 1,
        • "storage_bytes_read": 171,
        • "compute_ops": 1,
        • "processing_time_ms": 3,
        • "rate_limits_hit": [ ]
        }
      }
    ],
  • "cursor": "gsGCGmcS2P8aFEP9AAA=",
  • "has_next": false,
  • "stats": {
    • "read_ops": 9,
    • "storage_bytes_read": 481,
    • "compute_ops": 1,
    • "processing_time_ms": 7,
    • "rate_limits_hit": [ ]
    }
}

Event Stream endpoint

Subscribe to real-time events from an event source. See Event Streams.

The Event Stream endpoint maintains an open connection and pushes events to the client as they occur.

Authorizations:
bearerAuth
header Parameters
Authorization
required
string
Example: Bearer <FAUNA_SECRET>

A Fauna authentication secret, passed as a bearer token.

See Authentication for more details.

X-Query-Timeout-Ms
integer

Maximum runtime for the request in milliseconds.

Request Body schema: application/json
required
token
required
string

Event source token.

The event source token determines:

  • The events returned in the Event Feed.
  • The default start_ts, which is the event source query's timestamp.
cursor
string

Cursor for a previous event. If provided, the event source replays any events that occurred after the cursor (exclusive).

You can reuse cursors across event sources with identical queries in the same database.

You can't pass both start_ts and cursor.

If you don't provide a cursor or start_ts, start_ts defaults to the transaction timestamp of the query that created the event source.

start_ts
integer

Stream start time in microseconds since the Unix epoch. This is typically a previous event's txn_ts (transaction timestamp).

You can't pass both start_ts and cursor.

If you don't provide a cursor or start_ts, start_ts defaults to the event source query's timestamp.

For Event Streams, start_ts must be after the event source query's timestamp.

If start_ts is outside the history retention period of the source Set's collection, the stream returns an error event with the invalid_start_time error code.

Responses

Request samples

Content type
application/json
{
  • "token": "<EVENT_SOURCE>",
  • "cursor": "gsGabc123",
  • "start_ts": 1710968002310000
}

Response samples

Content type
application/json
Example
{
  • "type": "update",
  • "data": {
    • "@doc": {
      • "id": "412095363338469409",
      • "coll": {
        • "@mod": "Product"
        },
      • "ts": {
        • "@time": "2099-10-18T22:12:58.440Z"
        },
      • "name": "cups",
      • "description": "Translucent 9 Oz, 100 ct",
      • "price": {
        • "@int": "698"
        },
      • "stock": {
        • "@int": "100"
        },
      • "category": {
        • "@ref": {
          • "id": "412095363334275105",
          • "coll": {
            • "@mod": "Category"
            }
          }
        }
      }
    },
  • "txn_ts": 1729289578440000,
  • "cursor": "gsGCGmcS3WoaGjneAAA=",
  • "stats": {
    • "read_ops": 1,
    • "storage_bytes_read": 320,
    • "compute_ops": 1,
    • "processing_time_ms": 0,
    • "rate_limits_hit": [ ]
    }
}

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!