Documents

Mon, 01 Jan 0001 00:00:00 +0000

Every configured collection gets the same set of endpoints:

Method	Path	Behavior	Success
`POST`	`/v1/{realm}/{database}/{collection}`	Create a document	`201` + `Location` + `ETag`
`GET`	`/v1/{realm}/{database}/{collection}`	List documents	`200`
`GET`	`/v1/{realm}/{database}/{collection}/{id}`	Fetch one document	`200` + `ETag`
`PUT`	`/v1/{realm}/{database}/{collection}/{id}`	Replace the whole document	`200` + `ETag`
`PATCH`	`/v1/{realm}/{database}/{collection}/{id}`	Partial update (JSON Merge Patch)	`200` + `ETag`
`DELETE`	`/v1/{realm}/{database}/{collection}/{id}`	Delete the document	`204`
`POST`	`/v1/{realm}/{database}/_batch`	Create, replace, patch and delete atomically	`200`

An unknown realm, database, collection or id returns 404 not_found. PUT and PATCH never create documents: there are no upserts, so create with POST and let the server choose the id.
In a realm with auth: enabled, requests are decided by the collection’s access rules, or allowed outright with an API key in Authorization: Bearer ….
Request bodies must be a single JSON object. Anything else returns 400 invalid_json.

Document shape

Documents are returned as bare JSON objects:

Mon, 01 Jan 0001 00:00:00 +0000

The list endpoint, GET /v1/{realm}/{database}/{collection}, accepts these query parameters:

Parameter	Default	Meaning
`where`	—	JSON object with filter conditions
`order_by`	`id`	Comma-separated fields; prefix a field with `-` for descending
`limit`	`20`	Page size, `1`–`100`
`skip`	`0`	Number of documents to skip
`after`	none	The `next_cursor` of the previous page: continues the list after it (see Paging with a cursor). Can’t be combined with `skip`
`count`	`false`	`true` adds `total`, the number of documents matching `where`
`deleted`	none	In a collection with soft delete: `only` lists the deleted documents (the trash), `include` both. Needs the `restore` rule besides `read`

Each parameter may appear at most once. Any other parameter returns 400 invalid_query.