Overview

Truestamp exposes a JSON:API-compliant REST surface under the base path /api/json. It is an authenticated API: every endpoint requires a credential except the machine readable OpenAPI specification. Callers authenticate with an Authorization: Bearer header carrying either a Truestamp API key or an OAuth 2.1 access token. The surface is generated from Truestamp’s data model, so resources such as items, proofs, blocks, entropy observations, teams, and webhook endpoints appear as conventional JSON:API resource endpoints with standard filtering, sorting, and pagination. Two hosted documentation pages, Swagger UI and ReDoc, render the live specification so a developer can browse every operation and its request and response shapes.

Base path and authentication

All JSON:API traffic is served under /api/json. Individual resources hang off that prefix, for example /api/json/items for the items collection and /api/json/items/:id for a single item.

Authentication is mandatory. The one exception is the OpenAPI document at /api/json/open_api, which is served without a credential so tooling can discover the API. Every other route rejects an anonymous request with a 401 Unauthorized.

Present a credential in the standard bearer form:

Authorization: Bearer <api-key-or-oauth-access-token>

Two credential types are accepted on the same header:

• An API key issued to your account.
• An OAuth 2.1 access token obtained from Truestamp’s authorization server.

For OAuth callers, read operations (GET and HEAD) require the api:read scope and mutating operations (POST, PATCH, DELETE) require api:write. API-key callers are not scope-limited in this way. A request with a blank or malformed bearer token is rejected with a 401 rather than a server error.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://www.truestamp.com/api/json/items

Requests are rate limited per authenticated caller. Exceeding the per-minute budget returns 429 Too Many Requests with a JSON:API error body; slow down and retry shortly.

Discovery: OpenAPI, Swagger UI, and ReDoc

The API is self-describing. The full OpenAPI specification is generated from the live data model and served as JSON at /api/json/open_api. Because that document is the canonical source of every operation, path, parameter, and schema, it is the most reliable reference for exactly what the API accepts and returns.

Two human-friendly documentation UIs render that same specification:

• Swagger UI at /api/json/swaggerui: an interactive explorer that lists every endpoint and lets you inspect request and response schemas.
• ReDoc at /api/json/redoc: a clean, readable reference view of the same spec.

Both documentation pages and the raw spec are reachable without authenticating, so you can survey the API before wiring up credentials. Actually calling the resource endpoints still requires a bearer token.

Resource endpoints and conventions

The surface follows JSON:API conventions. Each resource is exposed at a base route, and operations map to HTTP verbs:

• GET /api/json/<resource>: list a collection.
• GET /api/json/<resource>/:id: fetch a single record by id.
• POST /api/json/<resource>: create a record.
• PATCH /api/json/<resource>/:id: update a record.

For example, the items resource supports listing, fetching by id, creating, and updating under /api/json/items. Some resources also expose action-style endpoints; the proof resource, for instance, accepts POST /api/json/proof/verify to verify a proof bundle, and the knowledge base accepts POST /api/json/kb/search, POST /api/json/kb/fetch, and POST /api/json/kb/links to search, read, and traverse the links between concepts (the same audience-gated tools the in-app assistant and the MCP server use). The OpenAPI spec is the authoritative list of which resources and operations exist.

One route to know early: GET /api/json/users/me (the currentUser operation) returns the authenticated caller’s own user record. It takes no parameters and is the canonical first call to confirm that a new API key or OAuth token works:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://www.truestamp.com/api/json/users/me

A 200 with your own user id in data.id confirms the credential; a 401 means the credential was missing, expired, or malformed.

Two sibling user routes exist on the same resource: GET /api/json/users (listUsers) and GET /api/json/users/:id (getUser). Both are visibility-filtered to the caller: the list returns you plus the members of teams you share, a get by id resolves only for yourself or a shared-team member, and sensitive fields are restricted field-by-field regardless of who is asking. There is no way to enumerate users outside your own teams.

Responses can embed related records. A request may ask for related resources to be included alongside the primary data (for example, an item can include its owning team, its author, and the block it was committed to), following the JSON:API include convention.

Tenant selection for multi-tenant resources

Some resources are scoped to a team. For those, the request selects which team it operates within, either with a tenant request header or a tenant query parameter carrying the team id:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "tenant: <team-id>" \
     https://www.truestamp.com/api/json/items

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://www.truestamp.com/api/json/items?tenant=<team-id>"

When no tenant is supplied, the request falls back to your default team preference if one is set and you still have a write-capable role on it, and otherwise to your personal team. A tenant you are not a member of is rejected with 403 Forbidden.

Utility endpoints

Six stateless utility operations live under POST /api/json/utilities: hash, verify-hash, uuidv7-timestamp, ulid-timestamp, resolve-id, and jcs-canonicalize. They compute hashes and canonical JSON, extract the time embedded in an identifier, and classify opaque ids; they create nothing, and their responses use a result envelope instead of a JSON:API resource document. Each has a GraphQL query twin. See the utility endpoints reference for the request and response shape, OAuth scope requirements, and the visibility gating on resolve-id.

Filtering, sorting, and pagination

Collection endpoints support the standard JSON:API query conventions for narrowing and ordering results, along with pagination for large result sets.

Pagination is controlled with the page family of query parameters:

• page[limit] sets the page size and must be a positive integer.
• page[offset] skips a number of records and must be a non-negative integer.

Each resource defines its own default and maximum page size. The items collection, for example, returns a bounded page by default and caps the page size at a per-resource maximum, so an oversized page[limit] is clamped rather than returning an unbounded result. Supplying a non-integer, zero, or negative page[limit], or a non-integer or negative page[offset], is rejected with a 400 Bad Request and a JSON:API error body.

Related surfaces

The JSON:API surface is one of several ways to integrate with Truestamp. A GraphQL endpoint exposes the same underlying data model with the same bearer authentication, and outgoing webhooks push delivery notifications to your own endpoints. Those are covered by their own concepts; this concept is the reference for the REST surface only.

Citations

1. JSON:API v1.1 Specification. Defines the resource object structure, include, sorting, and the page pagination conventions this surface follows.
2. OpenAPI Specification. The format of the machine-readable spec served at /api/json/open_api and rendered by the Swagger UI and ReDoc pages.