API Conventions

Behavioral conventions for the API — authentication, errors, rate limits, pagination, versioning, and anti-oracle behavior.

Schemas and endpoint signatures live in the API Reference. This page covers shared API behavior: authentication, errors, headers, pagination, rate limits, versioning, and privacy-preserving response patterns.

In This Section

Authentication — bearer tokens, cookie sessions, and required headers across endpoints.
Session Lifecycle — access tokens, refresh, locked sessions, and logout behavior.
Error Handling — problem details, status codes, and anti-oracle behavior.
Rate Limiting — rate limit tiers, headers, and retry behavior.

Request And Response Conventions

Convention	Detail
Content-Type (JSON)	`application/json` for all request and response bodies unless noted otherwise.
Content-Type (binary)	`application/octet-stream` for binary uploads (e.g. encrypted payloads).
Timestamps	ISO 8601 UTC — e.g. `2026-03-09T12:00:00Z`. No local offsets.
Binary fields	Base64-encoded strings wherever binary data appears in JSON (keys, ciphertexts, MACs).
Resource IDs	UUIDs. Always lowercase and hyphenated.

Versioning

All endpoints are served under the /v1/ prefix.

Versioning policy — The v1 prefix represents a stable contract. Breaking changes (removed fields, changed semantics, restructured endpoints) should ship under a new version prefix rather than silently changing v1 behavior.
Non-breaking additions — New optional fields in responses, new endpoints, and new query parameters may be added to v1 without a version bump. Clients should ignore unknown fields.
Deprecation — Before removing any v1 behavior, a deprecation notice and migration window will be communicated. Deprecated endpoints return a Deprecation header with a sunset date.

Pagination

Endpoints that return collections use page/limit pagination. All paginated responses follow this envelope:

{
  "items": [ ... ],
  "page": 1,
  "limit": 20,
  "total": 84,
  "total_pages": 5
}

Pass ?page=N to fetch a specific page (1-indexed, default 1).
Pass ?limit=N to control page size (default 20, max 100).
total is the count of all matching records; total_pages is derived from total / limit.

Anti-Oracle Behavior

For sensitive resource lookups, Literal avoids distinguishing “does not exist” from “not authorized.” Both cases return 404 Not Found with the same error shape where anti-oracle behavior applies.

This prevents callers from probing whether a document, entity, grant, or token-backed relationship exists.

Do not build client logic that depends on distinguishing missing resources from authorization failures for sensitive resource endpoints.

See Error Handling for the full problem details shape, and Blind Routing for the underlying privacy model.

What Belongs Where

This page	API Reference
Shared authentication behavior	Endpoint-level auth requirements
Error shape and anti-oracle behavior	Endpoint-specific status codes
Rate limiting behavior and headers	Per-endpoint rate limit tiers
Pagination envelope and versioning policy	Query parameter definitions
Content types, timestamps, and binary encoding	Request and response schemas

Last updated on