01 Documentation

Languages:

REST API Reference

The REST API provides straight-forward, resource-based access to FaunaDB. Any resource with a ref is available at its corresponding path.

Schema Endpoints

The endpoints /databases, /keys, /classes, and /indexes allow the creation of schema instances and pagination through existing instances.

GET /<schema class ref>

Get a list of existing schema instances.

Parameters      
ts Integer optional Return the set at the specified point in time.
after Cursor optional Return the next page of results after this cursor (inclusive).
before Cursor optional Return the previous page of results before this cursor (exclusive).
size Integer default 16 Maximum number of results to return.

The pagination cursor may be one of:

  • A URL-escaped JSON value.
  • A ref string without the { "@ref": ... } container.

Equivalent Query

{ "paginate": <schema class ref>, ... }

POST /<schema class ref>

Create an instance of a schema class.

POST accepts a JSON object via the request body.

Equivalent Query

{ "create": <schema class ref>, "params": { "quote": <body params> } }

The endpoints /databases/<name>, /keys/<id>, /classes/<name>, /indexes/<name> allow the retrieval and modification of instances of schema classes.

GET /<schema instance ref>

Get a schema instance.

Query Parameters      
ts Integer optional Return the instance at the specified point in time.

Equivalent Query

{ "get": <schema instance ref> }

PUT /<schema instance ref>

Replace a schema instance’s data.

PUT accepts a JSON object via the request body.

Equivalent Query

{ "replace": <schema instance ref>, "params": { "quote": <body params> } }

PATCH /<schema instance ref>

Update a schema instance.

PATCH accepts a JSON object via the request body.

Equivalent Query

{ "update": <schema instance ref>, "params": { "quote": <body params> } }

DELETE /<schema instance ref>

Delete a schema instance.

Equivalent Query

{ "delete": <schema instance ref> }

GET /<schema instance ref>/events

Get a schema instance’s event history.

Parameters      
ts Integer optional Return the set at the specified point in time.
after Cursor optional Return the next page of results after this cursor (inclusive).
before Cursor optional Return the previous page of results before this cursor (exclusive).
size Integer default 16 Maximum number of results to return.

The pagination cursor may be one of:

  • A URL-escaped JSON event
  • A timestamp

Equivalent Query

{ "paginate": <schema instance ref>, "events": true }

Instance Endpoints

The endpoint /classes/<name> allows the creation of instances of the corresponding class.

POST /<class ref>

Create an instance of a class.

POST accepts a JSON object via the request body.

Equivalent Query

{ "create": <class ref>, "params": { "quote": <body params> } }

The endpoint /classes/<name>/<id> allows the retrieval and modification of instances.

GET /<instance ref>

Get an instance.

Query Parameters      
ts Integer optional Return the instance at the specified point in time.

Equivalent Query

{ "get": <instance ref> }

PUT /<instance ref>

Replace an instance’s data.

PUT accepts a JSON object via the request body.

Equivalent Query

{ "replace": <instance ref>, "params": { "quote": <body params> } }

PATCH /<instance ref>

Update an instance.

PATCH accepts a JSON object via the request body.

Equivalent Query

{ "update": <instance ref>, "params": { "quote": <body params> } }

DELETE /<instance ref>

Delete an instance.

Equivalent Query

{ "delete": <instance ref> }

GET /<instance ref>/events

Get an instance’s event history.

Parameters      
ts Integer optional Return the set at the specified point in time.
after Cursor optional Return the next page of results after this cursor (inclusive).
before Cursor optional Return the previous page of results before this cursor (exclusive).
size Integer default 16 Maximum number of results to return.

The pagination cursor may be one of:

  • A URL-escaped JSON event
  • A timestamp

Equivalent Query

{ "paginate": <instance ref>, "events": true }

Other Endpoints

POST /tokens

Create a token on a user’s behalf.

Parameters      
email String optional The user’s email address.
password String optional The user’s password. Required if a client key is used.
match String optional A unique index value.
index Ref optional An index of users or settings.

GET /ping

Check service health. For a given scope, a successful ping means the following:

  • node: the responding node is available.
  • local: the local datacenter is available.
  • global: the global cluster is available.
  • all: all nodes in the cluster are available.

The default scope is global.

Responds with 200 OK on success, 503 on timeout, or 500 if a data inconsistency is detected.

Parameters      
scope String optional One of node, local, global, or all.
timeout Integer optional Time to wait for the ping to succeed, in milliseconds.