Skip to main content
GET
Get a document, its answers and optional history

Authorizations

Authorization
string
header
required

An organization API key. Keys carry a role (read_write or read_only) and may be restricted to a namespace prefix such as acme/*, or to one namespace such as acme/prod/tenant_1. A prefix matches on a / boundary: acme/prod/tenant_1* covers acme/prod/tenant_1 and everything under acme/prod/tenant_1/, never acme/prod/tenant_12.

Path Parameters

ns
string
required

The namespace name, with any / sent as %2F. Up to 256 bytes. / separates levels of the hierarchy, as in acme/prod/tenant_123.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9._:/-]+$
id
string
required

The document id, with any / sent as %2F. Up to 128 bytes.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9._:/-]+$

Query Parameters

include
enum<string>[]

history adds the evaluation records of the current incarnation, newest first. context adds each evaluation's compiled context and raw the engine's raw response; both are large and only apply with history.

Available options:
history,
context,
raw
history_limit
integer

Maximum evaluation records returned with include=history.

Required range: x >= 1
all_incarnations
boolean
default:false

Include history from earlier lives of the same id.

answers
string[]

Judgment names whose answers to return.

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
wait_ms
integer

How long to wait for on_read answers before returning them pending.

Required range: 0 <= x <= 10000

Response

The document.

id
string
required

Up to 128 bytes.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9._:/-]+$
revision
integer<int64>
required

The namespace sequence at which the document last changed. Monotonic, not contiguous.

Required range: x >= 0
incarnation
integer<int64>
required

The sequence at which this document was created or re-created after a delete.

Required range: x >= 0
attributes
object
required

Flat, filterable and sortable. At most 64 keys. Not sent to engines unless a context recipe names them.

state
object
required

The JSON content judgments are made about. At most 1 MB. Never filterable.

created_at
string<date-time>
required

When this incarnation was created, the time of the write that created it unless that write gave its own created_at. Relations order by it, and window and freshness.fanout.scope count from it.

updated_at
string<date-time>
required

RFC 3339, UTC.

answers
object
required

Answers keyed by judgment name.

usage
object
required

What this response billed (§6.1).

history
object[]

With include=history, evaluation records newest first.