API docs by Redocly

Fauna Core API

Download OpenAPI specification:Download

You can use the Fauna Core HTTP API to run FQL queries and consume event streams.

The Fauna client drivers and the Fauna Dashboard 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 in API requests as a bearer token.

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. In the Dashboard, create a database and navigate to it.

  3. In the upper left pane of the Dashboard's Explorer page, click the demo database, and click the Keys tab..

  4. Click Create Key.

  5. Choose a Role of server.

  6. Click Save.

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

Query endpoint

Runs an FQL query. In Fauna, every query is a transaction that runs in the context of a single database.

Endpoint conventions

For other conventions for this endpoint, see Query API endpoint conventions.

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. Defined the arguments parameter or within objects passed to the query parameter.

Accepts simple (default) and tagged.

For more information, see Wire Protocol.

X-Last-Txn-Ts
integer

If set, acts as the minimum snapshot time the query executes. Clients populate this based on the highest txn_ts result value observed of any transaction the client has processed.

X-Linearized
boolean

If true, unconditionally run the query as strictly serialized. This affects read-only transactions because transactions that write are already strictly serialized. See Strictly serialize read-only transactions.

X-Max-Contention-Retries
integer

The maximum number of times the system retries a transaction because of contention failure before an error is returned.

X-Query-Tags
string

A string-encoded set of caller-defined tags, which identify the request. Provided back in the logging and the query response body. The format is a list of key:value pairs. For example:

  • foo=bar
  • foo=bar,baz=blah

Each key and each value may only include the characters [a-zA-Z0-9_]. These are also valid tags:

  • foo_bar=baz
  • foo3=1234,5=6

All these are invalid:

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

Each key must be less than or equal to 40 bytes. Each value must be less than or equal to 80 bytes. There can be only a maximum of 25 key:value pairs, and the full header can't exceed 3000 bytes.

X-Query-Timeout-Ms
integer

Query timeout in milliseconds.

X-Typecheck
boolean

Enable or disable type checking of the query before evaluation. Defaults to the value of typechecked on the database configuration.

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

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

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 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
}

Stream endpoint

Subscribe to real-time events from a stream. See Event Streaming.

The Stream endpoint maintains an open connection and pushes events to the client as they occur. To asynchronously poll a stream for events, use the Event Feed endpoint.

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

Query timeout in milliseconds.

Request Body schema: application/json
required
token
required
string

Stream token for the event stream to subscribe to.

cursor
string

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

You can't pass both start_ts and cursor.

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 stream creation timestamp. The stream creation timestamp is set when you first subscribe to or poll the stream.

Responses

Request samples

Content type
application/json
{
  • "token": "<STREAM_TOKEN>",
  • "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": [ ]
    }
}

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 stream as a paginated Event Feed.

The Event Feed endpoint lets you periodically poll a stream for events. To synchronously subscribe to events, use the Stream endpoint.

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

Query timeout in milliseconds.

Request Body schema: application/json
required
token
required
string

Stream token for the event stream to subscribe to.

cursor
string

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

You can't pass both start_ts and cursor.

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 stream creation timestamp. The stream creation timestamp is set when you first subscribe to or poll the stream.

page_size
integer

Maximum number of events to return per page. Defaults to 16.

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

Responses

Request samples

Content type
application/json
{
  • "token": "<STREAM_TOKEN>",
  • "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": [ ]
    }
}

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!