API Conventions

Schemas and endpoint signatures live in the API Reference. This page covers behavior — how authentication works, how errors are shaped, what headers to expect, and the guarantees the server makes.

Schemas and endpoint signatures live in the API Reference. This page covers behavior — how authentication works, how errors are shaped, what headers to expect, and the guarantees Literal makes.

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 (v4). Always lowercase, hyphenated — `550e8400-e29b-41d4-a716-446655440000`

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) will ship under a new version prefix (/v2/), never silently within v1.
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

Idempotency

Not Yet Implemented

Idempotency-Key support is planned but not currently enforced. The behavior below is the intended contract once middleware ships.

Select write endpoints will support idempotency via the Idempotency-Key header:

Pass a client-generated UUID as Idempotency-Key: <uuid>
The server stores the response for a given key and replays it on retry, preventing duplicate side effects
Keys expire after 24 hours — retries after expiry are treated as new requests
If a request with the same key is already in flight, the server returns 409 Conflict
Not all endpoints will support idempotency keys — check individual endpoint docs in the API Reference for support

The Anti-Oracle Guarantee

The server never distinguishes "doesn't exist" from "you can't access it."

If you request a resource that is missing or that your token doesn't grant access to, you get a 404 Not Found with the message "not found or access denied." Both cases return the same status code and the same response shape. This is deliberate — distinguishing "doesn't exist" from "you can't access it" would leak information about what exists in the system (an "oracle"), which is a security problem for a privacy-focused API.

This is called anti-oracle behavior and is applied to resource endpoints for documents, entities, and grants. See the Error Handling page for the full RFC 7807 error shape and the Blind Routing docs for why this matters.

What Belongs Where

This page (API Conventions)	API Reference
Auth flow, token lifecycle, error shapes	Endpoint signatures, request/response schemas
Rate limiting behavior and headers	Per-endpoint rate limit tiers
Anti-oracle guarantee, idempotency semantics	Field-level validation rules
Pagination envelope, versioning policy	Query parameter definitions