JSON:API HTTP Surface
The authenticated JSON:API REST surface at /api/json, its API-key or OAuth bearer auth, the OpenAPI spec plus Swagger UI and ReDoc discovery pages, resource-oriented endpoints, tenant selection, filtering, and pagination conventions.
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 and the two documentation pages that render it. 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, blocks, entropy
observations, teams, and webhook endpoints appear as conventional JSON:API
resource endpoints with standard filtering, sorting, and pagination. Proof
generation and verification ride the same surface as action-style routes. 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. An item’s :id there is its id (a UUIDv7),
its item code in either case (with at most one hyphen, underscore or space between
its groups of four) or its item_hash; the answer’s id is always the UUID, with
item_code among its attributes, and an unknown item, one you may not read, a
malformed value and a code typo all get the same 404, whose detail is always “No
item record found”. A write (PATCH /api/json/items/:id and its /unredact) takes
the UUIDv7 id alone, in either case: a code, an item_hash, a padded id and any
other value get that same 404 and change nothing. The items list filters by code
too, filter[item_code]=<CODE>.
Authentication is mandatory. The exceptions are the discovery surfaces: the OpenAPI
document at /api/json/open_api and the two documentation pages that render it
(/api/json/swaggerui and /api/json/redoc). All three are served without a
credential so tooling and developers 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. There is one carve-out:
a small, explicitly enumerated set of POST routes that only read require api:read
too. Ash mounts a generic action as a POST route even when it writes nothing, so the
verb alone would over-demand the write scope. The read-only POST routes are the three
knowledge-base tools (/api/json/kb/search, /api/json/kb/fetch, /api/json/kb/links),
the six utilities (/api/json/utilities/hash, /verify-hash, /uuidv7-timestamp,
/resolve-id, /jcs-canonicalize, /server-time), the two
proof operations
(/api/json/proof/generate, /api/json/proof/verify), and the raw verify route
(/api/json/proof/raw/verify). Every other POST, PATCH, and
DELETE still requires 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, falling back to your network
address when a request carries no credential. Exceeding the budget returns
429 Too Many Requests with a JSON:API error object whose code is "rate_limited"
and whose meta carries retry_after_ms, the wait in milliseconds, and limit, the
budget that was reached. Wait that long and retry.
A refusal from the API pipeline also carries a Retry-After header in whole seconds.
Some limits are enforced deeper, on the operation rather than the request, and those
refusals carry the same body without the header, so read meta.retry_after_ms and treat
the header as a convenience when it is present.
Limits are enforced across the whole fleet with eventual consistency: each
server counts what it admits and shares that count with its peers within a
fraction of a second, so a burst of many requests sent at the same instant can
be admitted a few percent past the limit before the servers agree. The
per-caller budget is a token bucket: you may spend the whole budget at once and
then continue at the refill rate, and a refusal’s Retry-After is your own
short wait for the next token. The per-address guard below is a window aligned
to the clock minute, so add a little random jitter to its Retry-After rather
than retrying on the exact second; otherwise every refused client retries
together at the boundary.
Before any credential is examined, each API surface also limits requests per client
address (an IPv4 address or an IPv6 /64) to 1,000 per minute. A flood of missing or bad
credentials is therefore refused with the same 429 before it reaches the database, and
a request can be refused before it is authenticated. Authenticated traffic is charged
against both the per-address and the per-user budget.
Two operations are also limited per call, on every surface and inside an MCP script:
proof generation at 300 per minute per account (3,000 fleet-wide) and proof
verification at 30 per minute per account, online or offline. A refusal from these
carries the usual rate_limited body without a Retry-After header.
Request size limits
A request body to /api/json may be at most 528,384 bytes: twice 262,144 plus 4,096. That leaves room for a proof of up to 256 KB (262,144 bytes) even when it is sent escaped inside a JSON string, which can double its size, plus the rest of the document. The limit is checked before the body is parsed.
- Over the limit:
413. A body over the limit is refused with413 Content Too Largeand a JSON:API error whosecodeisrequest_too_largeand whosemeta.max_bytesis the limit. A declaredContent-Lengthover the limit is refused before any of the body is read. A JSON or form-encoded body sent without one, such as a chunked upload, is read only until it passes the limit. On HTTP/1.x a413also closes the connection. - No length where one is needed:
411. Any other non-empty body sent without aContent-Length, such as a multipart upload, a body of another content type, or a body on aGET, is refused with411 Length Requiredand the codelength_required. Send it again with itsContent-Length. An empty body, as on an ordinaryGET, passes.
A JSON body sent with POST, PATCH or DELETE (application/vnd.api+json or application/json), the normal case for this API, is never asked for its length.
Creating an item (POST /api/json/items) takes a JSON:API document only. Items take no files, so a multipart form there is refused with 415 Unsupported Media Type and the code unsupported_media_type before its claims are read. Other operations accept a multipart form as before.
Repeated member names
A JSON body in which any object has two members with the same name is refused with 400 Bad Request, at any depth, including inside a claims object and in the JSON data part of a multipart request. JSON leaves the meaning of a repeated name to each reader, and readers disagree on which of the two they keep, so the server never picks one. Two names are the same when they are the same characters once JSON escapes are read: "a" and "\u0061" are the same name, while two Unicode spellings of é (one character, or e followed by a combining accent) are different names. The error names the member (member order in errors is not significant):
{"errors":{"detail":"A JSON object in the request has two members named \"name\".","member":"name"}}
A name longer than 64 characters is cut to its first 64 in member, and detail then ends with “(its first 64 characters).” When a body holds more than one repeat, the one named is the repeat whose second occurrence comes first. A client that does not ask for JSON (no Accept header, */*, or text/html) gets an HTML error page with the same sentence instead.
A number in a JSON body may be at most 1,024 characters as written, sign, point and exponent included. A body holding a longer one gets the plain 400 Bad Request before anything reads it. Send a longer number as a string. The same limit holds for a JSON text sent as a string where an object is taken, such as the json of jcs-canonicalize or a webhook’s custom_headers: such a text holding a longer number is refused before it is read, with the ordinary invalid-value error, whose detail says a number in the JSON text has more than 1,024 characters. The proof of proof/verify is a string, the proof’s text, read exactly as a proof file is, so text that is not a proof, one holding such a number included, is refused before any check with the code malformed_json and a sub_reason naming the rule it breaks.
Error bodies
Errors from an operation come back as a JSON:API errors array. Each entry carries
status, code, a human-readable detail, and, where the error is about a specific
input, a source pointer naming it. A body that is refused before any operation runs
because it cannot be read as JSON gets a plainer shape instead: an errors object
holding only a detail, {"errors":{"detail":"Bad Request"}}, or, for a repeated
member name, the detail and member shown above. Under /api/json that body is
served as application/vnd.api+json; every other surface serves it as
application/json.
An error with a bound value renders that value in both forms. detail reads as prose
with the value substituted, and meta carries the bindings separately for a caller
that would rather branch on the number than parse the sentence:
{
"errors": [
{
"status": "400",
"code": "invalid_argument",
"source": { "pointer": "/data/attributes/limit" },
"detail": "must be less than or equal to 12",
"meta": { "max": 12 }
}
]
}
Prefer code and meta for anything programmatic. detail is prose and may be
reworded; the pair is offered so that reading it is never the only option.
A claims violation from an item create is the exception: it carries no meta. Its
detail names the member it concerns, a name you chose, and is sent exactly as
written, so the programmatic fields are its code (such as claims_null) and its
source.pointer under /data/attributes/claims.
An item create can also be refused with 409 Conflict and the code
item_code_unavailable, with no source and no meta: the item could not be given
an item code that no other item holds. Nothing is stored, so send the same request
again.
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.DELETE /api/json/<resource>/:id: delete a record.
Not every resource exposes every verb. Many are read-only, and the write verbs appear
only where a matching action is published: for example, the items resource supports
listing, fetching by id, creating, and updating under
/api/json/items, and restoring a redacted item with
PATCH /api/json/items/:id/unredact, while webhook endpoints additionally support delete. Some resources
also expose action-style endpoints; the proof resource, for instance, accepts
POST /api/json/proof/generate to generate a proof and POST /api/json/proof/verify
to verify one, 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 knowledge-base reads the in-app
assistant and connected AI agents use). The OpenAPI spec is the authoritative list of
which resources and operations exist.
The ledger resources carry the records a proof is built from. An item carries
claims_jcs, claims_hash, witness_hashes (its witnesses), item_hash and item_code;
an entropy observation carries its captured entropy, entropy_hash and
observation_hash; neither carries a signature, since neither is signed. A block carries
its record’s members (height, leaf_count, merkle_root, metadata,
previous_block_hash) with its block_hash, signature and signing_key_id. A row of
/api/json/commitments is one kind of commitment at two levels: subject_kind (item,
observation or block) and tree_kind (block or epoch) say which, the row names its
subject and its tree by id, tree_block_id for a block’s tree or epoch_id for an
epoch’s, carries inclusion_proof, and, for a block in an epoch, the epoch’s chain. A
block’s commitment into an epoch whose hash Truestamp wrote to Stellar or Bitcoin is such a
row. An epoch, at /api/json/epochs, carries chain, network, leaf_count,
epoch_hash, the heights and block ids of its range, and its state; its epoch_hash is
the value written to the chain.
PATCH /api/json/items/:id/unredact restores a redacted item’s claims. Its attributes
hold claims_json, the item’s original claims as a JSON text of at most 65,536 octets,
kept exactly as sent; any formatting of the same claims restores, such as the item’s
claims_jcs or a proof’s subject.claims written as JSON. Only claims whose claims
hash is the one the item kept restore it. Claims that do not match get a 400 whose
detail says “These claims do not match the original. Only the exact original claims,
nonce included, can restore this item.” Claims that are not readable JSON, are not a
JSON object or are over 65,536 octets get a 400 whose detail names that problem
instead, and a claims_json of whitespace only counts as missing, a 400 saying it is
required. It needs api:write and the right to restore the item (its user owner, or an
admin or owner of the team that owns it; only a Truestamp system administrator undoes a
compliance redaction), and the tags removed with the claims are not restored. Redacting
is not on the API: the item’s page has you download the item’s last proof before it
redacts. See the item lifecycle.
POST /api/json/proof/generate takes the subject id and an explicit subject type
(there is no auto detection), and an optional constructions of full (the default),
reference or none, which says how the proof carries the constructions text that
defines every recomputed value: the text itself, a reference to its published copy, or
neither. Each mode is its own signed document, and the verdict never depends on it. For
type item, the id is the item’s UUIDv7, its item code or its item_hash. The
result is a string: the proof’s exact bytes, the signed document Truestamp serves once
its own verifier has checked it (see
the proof bundle wire format). Hand it on
unchanged. Every proof of an item carries every witness its fingerprint names.
POST /api/json/proof/verify takes proof, that text, an optional expected_hash, and
offline: the run reads the public chains and sources the proof names unless offline
is true, within one minute for the whole run. trace: true adds the run’s trace, as the
text of a trace file. The result is the report: label (verified,
internally-consistent or failed), verified, code when failed, attribution,
environment, trust_root, type, subject_id, window (established or
not_established) and beside it the two edges submitted_after and submitted_before,
and rows, one per check in order. A document the verifier refuses before any check
gives no report: the error’s meta.code is malformed_json, invalid_envelope or
input_too_large, with meta.sub_reason naming the rule, and verification_unavailable
means the server could not run the verifier.
Two raw routes take the proof outside a JSON:API document, under the same authorization and limits as the actions they run:
GET /api/json/proof/raw/:type/:idanswers the proof’s exact bytes asapplication/vnd.truestamp.proof+json, with the query parameterconstructions; an item is found by its UUIDv7, item code oritem_hash, always a200with no redirect.POST /api/json/proof/raw/verifytakes a proof file’s bytes as the body, whatever its content type, at most 262,144 bytes, with the query parametersoffline=trueandexpected_hash, and answers the report alone, as JSON.
Transient refusals are worth telling apart from terminal ones, because only the
transient ones are worth retrying. no_block_commitment, commitment_not_final and
subject_not_ready are transient: the subject or its block has not reached a
verifiable stage yet, and a later commitment gets it there. evidence_unconfirmed,
signing_unavailable, witness_unavailable (meta.witness names the witness) and
lookup_failed are transient too: Truestamp could not confirm the chain evidence, sign
the proof, find a witness or read a record just now, so it issues no proof rather than
a smaller one, and a later request can succeed. subject_redacted and
proof_too_large are terminal, and so is generation_failed, whose meta.reason
names why Truestamp’s own records gave no proof its verifier accepts.
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 team, its
creator, 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, resolve-id, jcs-canonicalize, and
server-time. They compute hashes and canonical JSON, read the time Truestamp
recorded inside a UUIDv7 id, classify opaque ids, and read the server’s clock;
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.page[after]andpage[before]carry an opaque cursor.
Collections that page by cursor, the items collection among them, return next and prev
links that already carry the right page[after] or page[before] cursor. Follow those
links rather than constructing cursors yourself. The collections that grow without bound -
items, beacons, blocks, entropy observations, commitments and epochs - return a bounded
page of 25 by default even when you send no page parameters, so a first request never
hands back an entire table.
Each resource defines its own default page size, and every paginated collection has a
maximum: 250 unless the resource declares its own. There is no unbounded page. An
oversized page[limit] is clamped to that maximum rather than rejected, so a large value
returns a full page instead of a 400. A clamped page is still a complete page: it
carries the clamped size in meta.page.limit and, when more records remain, a next link
that continues from where it ended. Paging by next therefore reaches every record no
matter what page[limit] was asked for. 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
- JSON:API v1.1 Specification. Defines the resource
object structure,
include, sorting, and thepagepagination conventions this surface follows. - OpenAPI Specification. The format of the
machine-readable spec served at
/api/json/open_apiand rendered by the Swagger UI and ReDoc pages.