Knowledge Base

Browse the concepts behind Truestamp. Follow the links between concepts, or search across everything.

GraphQL API

The authenticated GraphQL endpoint at /gql and its interactive playground, requiring an API key or OAuth bearer token, with queries and mutations auto-generated from the Truestamp resource domains and an introspectable schema.

Overview

Truestamp exposes a GraphQL API at the /gql endpoint. It is an authenticated surface: every query and mutation you execute requires a credential, either an API key or an OAuth 2.1 bearer token, sent as an Authorization: Bearer header. The schema is generated automatically from Truestamp’s resource domains (teams, items, blockchain, entropy, proofs, beacons, webhooks, the knowledge base, and more), so the available queries and mutations mirror the same operations offered elsewhere. The knowledge base, for example, is searchable and readable here through the kbSearch, kbFetch, and kbLinks queries, the same audience-gated tools the in-app assistant and the MCP server use.

Every query that wraps an operation rather than a record (the three knowledge-base queries, generateProof and verifyProof, and the six utility queries) answers with the same { result, errors } envelope a mutation has: select result for the operation’s JSON string and errors { code message vars } for anything that went wrong with that one field. A failure inside the envelope never nulls the rest of the document, so several of these fields can be aliased in one request and each reports its own outcome. generateProof takes id, type and an optional constructions (full, reference or none), and its result is the proof’s text, its exact bytes; verifyProof takes that text as proof, a String, with expectedHash, offline and trace, and its result is the verification report as a JSON string. Because GraphQL is introspectable, the best way to learn the surface is to open the interactive playground at /gql/playground and explore the schema live.

This is the companion surface to the JSON:API. Both speak to the same underlying resources over HTTP; pick GraphQL when you want to shape the exact fields and nested relationships returned in a single request.

The endpoint

GraphQL operations are sent as HTTP POST requests to /gql with a JSON body containing your query (or mutation) string and optional variables. On the production app the full URL is https://www.truestamp.com/gql; in local development it is http://localhost:4000/gql.

A minimal request with curl:

curl -X POST https://www.truestamp.com/gql \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "{ health { status version } }"}'

The health query is a lightweight status check that returns the service status, the application version, and build. It is a convenient first call to confirm your credential and connectivity are working before you explore further.

version and build answer different questions. version is the application version pinned in mix.exs and does not move between releases; build is the git commit the running artifact was compiled from, so it identifies the deployed build exactly. build reads "dev" when no build identity was baked in, which covers a local instance and any image built before the field existed.

Requests are subject to a per-caller rate limit and a query-complexity ceiling, so deeply nested or overly broad queries may be rejected. Keep individual queries focused on the fields you actually need.

A request body to /gql may be at most 528,384 bytes, which leaves room for a proof of up to 256 KB (262,144 bytes) passed escaped in the proof argument of verifyProof, where escaping can double its size. The limit is checked before the body is parsed. A body over it is refused with 413 Content Too Large and an error whose extensions carry code: "request_too_large" and max_bytes, the limit; a declared Content-Length over the limit is refused before any of the body is read. A non-empty body that is not JSON or form-encoded, such as an application/graphql document, sent without a Content-Length is refused with 411 Length Required and code: "length_required": send it again with its length. A JSON POST, the normal case, is never asked for its length.

Numbers are bounded before anything reads them:

  • A number literal in the document, an Int or Float written in the query itself, may be at most 32 characters, sign, point and exponent included; no 64-bit integer or double needs more. A longer one is refused before anything runs, with no data and one error at the literal whose message names the limit: “A number literal may have at most 32 characters, and this one has 40. Send a longer number as a string.” A number inside a string is not a literal: the claims text of createItem is judged by the claims rules.
  • A number in a JSON text, in the request body or in a JsonString, JsonObject or Json value sent as a string (such as the json of jcsCanonicalize or a block’s metadata in a listCommitments filter), may be at most 1,024 characters as written. In the body, a longer one gets 400 Bad Request; in an argument, as a literal or a variable, the response has no data and one error saying a number in the JSON text has more than 1,024 characters.

JSON in which any object has two members with the same name is refused with 400 Bad Request and the member named, on /gql and on the playground alike, because readers disagree on which of the two a repeated name means. Two names are the same when they are the same characters once JSON escapes are read, so "x" and "\u0078" are the same name. A name longer than 64 characters is named by its first 64, and the message then says so. The shape depends on where the repeat is:

  • In the request body: the member in errors.member (member order in errors is not significant), or an HTML error page with the same sentence for a client that does not ask for JSON.

    {"errors":{"detail":"A JSON object in the request has two members named \"x\".","member":"x"}}
  • In variables sent as a JSON string: a GraphQL error list with the member in errors[].extensions.member. This holds wherever the string is: the body, a form field, the query string, or one query of a batch, including a batch sent as a string.

    {"errors":[{"message":"A JSON object in the request has two members named \"x\".","extensions":{"member":"x"}}]}
  • In a multipart request’s operations, or in a batch sent as a JSON string, outside any variables string: the member is named in the message. On the playground, a request asking for HTML gets the message alone as the body, with no Content-Type header.

    {"errors":[{"message":"Could not parse JSON. A JSON object in the request has two members named \"x\"."}]}

All three JSON refusals, and the plain {"errors":{"detail":"Bad Request"}} a body that is not valid JSON gets, are served as application/json.

A rate-limit refusal arrives as 429 Too Many Requests, with a Retry-After header in whole seconds when the pipeline refused the request. In the response body the error carries code: "rate_limited" and retry_after_ms, the wait in milliseconds: on a pipeline refusal under extensions, and on an operation-level refusal under vars alongside the limit that was reached. retry_after_ms is the field to act on; the header is only present on pipeline refusals.

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 GraphQL document that aliases generateProof or verifyProof many times is charged once per alias; a refused alias comes back with result: null and a rate_limited entry in its own errors, and the admitted aliases keep their results.

Authentication

Every GraphQL operation you would write a client against requires authentication (see the playground exception below). Two credential types are accepted, both presented as an HTTP bearer token:

  • An API key, sent as Authorization: Bearer <api_key>.
  • An OAuth 2.1 access token, sent as Authorization: Bearer <access_token>.

If no credential is supplied, or the credential is invalid or expired, the endpoint responds with 401 Unauthorized. The response includes a WWW-Authenticate: Bearer challenge header and a GraphQL-style errors envelope so clients get a machine-readable hint about what went wrong.

There is one deliberate exception: loading the playground page itself. A GET to /gql/playground from a browser is served without authentication so the UI can render. Everything the UI then does is a POST and needs your credential like any other client, including the introspection call that populates its Docs panel and autocomplete. So set your Authorization header in the playground’s own HTTP-headers pane before running anything.

The exemption is written against the browser’s Accept header as well as the method and path, so it covers a page load and nothing else: a GET carrying an operation is refused like any other uncredentialed request.

The path half is matched on a segment boundary, so it covers /gql/playground and paths beneath it and nothing else. A lookalike that merely starts with the same characters, such as /gql/playgroundx, is not the playground and gets no exemption; it is refused with a 401 like any other uncredentialed request.

The playground is read-only

/gql/playground serves queries and introspection. Mutations are refused there with a read_only_surface error whatever credential you present, because it is the one GraphQL entry point whose page loads without one. Point a client at /gql to write; it is the same schema and the same credentials.

Read-only is the only difference. A query you run there is executed AS YOU, with the same actor and team scoping as the same query against /gql, so me returns your user and your own items and teams are visible. If me comes back null while your header is set, the credential reached the server but the actor did not, and you are looking at a bug rather than at an empty account.

Read and write scopes for OAuth callers

Queries and mutations are both POST requests, so the read/write distinction is enforced in two places for OAuth callers. Any GraphQL call requires the read scope (api:read). Mutations additionally require the write scope (api:write); an OAuth token that lacks it is rejected with an insufficient_scope error before the mutation runs. API-key callers are not scope-limited, so this split does not apply to them.

The split follows what an operation actually does, not how it feels. Every operation that only reads is exposed as a query, including ones that take a substantial payload: generateProof and verifyProof are queries, as are the kbSearch / kbFetch / kbLinks tools and the utility operations. A read-only agent holding just api:read can therefore generate and verify proofs without being handed the ability to create items or change teams.

The interactive playground

The playground at /gql/playground is an in-browser GraphQL IDE. Open it in a browser to:

  • Browse the full schema, including every query, mutation, type, and field, through built-in introspection and the schema documentation panel.
  • Compose and run operations with autocompletion and inline validation.
  • Set request headers, including your Authorization: Bearer <token> header, so operations you run from the playground are authenticated.

Because the schema is fully introspectable, the playground’s documentation explorer is the authoritative, always-current catalog of what you can query and mutate. Rather than memorizing operation names, start there and let autocompletion guide you.

Exploring the schema

The GraphQL schema is generated from Truestamp’s resource domains, so the set of available operations tracks the resources and actions the platform exposes. Rather than enumerating them here, use introspection to discover the surface:

  • Open /gql/playground and read the documentation explorer, which lists every query and mutation with its arguments and return types.
  • Run an introspection query (for example, requesting __schema { queryType { fields { name } } }) from any authenticated client to fetch the same catalog programmatically.

Queries read data; mutations change it. Field selection lets you request exactly the attributes and nested relationships you need in one round trip, which is the main reason to prefer GraphQL over a fixed-shape REST response.

Two families of queries are worth knowing by name. The me query returns the authenticated caller’s own user record (the GraphQL twin of the REST surface’s GET /api/json/users/me), a convenient credential check alongside health. And six stateless utility queries, hash, verifyHash, uuidv7Timestamp, resolveId, jcsCanonicalize, and serverTime, mirror the POST /api/json/utilities/* routes; see the utility endpoints reference for their arguments, result shapes, and the visibility gating on resolveId.

The ledger types carry the records a proof is built from. An Item carries claimsJcs, claimsHash, witnessHashes (its witnesses), itemHash and itemCode; an EntropyObservation carries its captured entropy, entropyHash and observationHash; neither carries a signature, since neither is signed. A Block carries its record’s members (height, leafCount, merkleRoot, metadata, previousBlockHash) with its blockHash, signature and signingKeyId, its own commitments into epochs, and leafCommitments, the commitments of what its tree holds. A Commitment is one kind of row at two levels: subjectKind (item, observation or block) and treeKind (block or epoch) say which, it names its subject (item, entropyObservation or subjectBlock) and its tree (treeBlock or epoch), carries inclusionProof, and, for a block in an epoch, the epoch’s chain. An Epoch carries chain, network, leafCount, epochHash, the heights and block ids of its range (fromHeight, toHeight, fromBlockId, toBlockId), and its state; its epochHash is the value written to the chain.

Reading an item

The getItem query takes id, which names the item by 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 64-hex item_hash, read exactly as sent. An item that does not exist and one you may not read both answer null, with no error, and so does any other value. Every Item carries itemCode, its code in canonical form. The writes, updateItem and unredactItem, take the item’s UUIDv7 id alone: a code, an item_hash or a padded id is refused as not found.

Creating an item

The createItem mutation takes the claims as claimsJson: a required string holding the claims as a JSON text, at most 65,536 bytes, with the claims’ own member names (hash_type). GraphQL input objects would rewrite JSON (member names, types, nested strings), so the claims travel as text and are committed exactly as sent. An empty text, or one of only whitespace, is refused as a missing argument. A successful create returns claimsJcs, the exact canonical bytes of the claims, and claimsHash, computed over them. See submit an item for the claims rules and an example.

Claims that break a rule come back in the mutation’s errors, one entry per broken rule:

  • code: the rule’s stable code, such as claims_empty or claims_not_nfc, the same codes the JSON:API returns;
  • message: what is wrong and how to fix it, sent exactly as written, even when it quotes one of your member names;
  • vars.pointer: a JSON pointer (RFC 6901) to the member within your claims, "" for the claims as a whole. A repeated member name, and a number out of range (one no double holds, or a whole number beyond +-(2^53-1) as canonical form writes it, such as 1e20 or 9007199254740992), are found as the text is read, which reports no place, so they point at "". The message still names the reason. A number with more digits than canonical form keeps (claims_number_precision, such as 3.14159265358979323846, which would be stored as 3.141592653589793) and a number too close to zero to hold point at the number itself;
  • fields: ["claims_json"], and path: ["input", "claimsJson"].

Two refusals come before the claims rules run, and carry no claims code:

  • a claims text that is not valid UTF-8 cannot be a JSON string, so in a JSON request body the endpoint refuses the whole request with 400 before GraphQL runs; in an application/graphql document the document fails to parse, and the response has no data and one top-level entry in errors with no code;
  • a raw NUL character (U+0000) anywhere in the text is refused by the check every GraphQL argument passes: the response has no data, and one top-level entry in errors whose message says that claimsJson must not contain a NUL byte, with no code.

Nothing is stored in either case.

A create can also come back with result: null and one entry in errors whose code is item_code_unavailable and whose fields is empty: the item could not be given an item code that no other item holds. Nothing is stored, so send the same mutation again.

A JsonObject value written as an object or list literal keeps every string in it exactly as written: {count: "42"} stays the string "42". Only a whole value sent as a string is read as JSON.

Restoring a redacted item

The unredactItem mutation restores a redacted item’s claims and returns it to committed. It takes the item’s id and, in its input, claimsJson: 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 claimsJcs or a proof’s subject.claims written as JSON. Claims whose claims hash is not the one the item kept come back in errors with the message “These claims do not match the original. Only the exact original claims, nonce included, can restore this item.” 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. There is no redact mutation: the item’s page has you download the item’s last proof before it redacts. See the item lifecycle.

Multi-tenancy

Many resources (such as items) are scoped to a team. As with the other authenticated API surfaces, you can target a specific team by supplying a tenant value (a team id) on the request; when omitted, operations resolve against your default or personal team. Supplying a team you are not a member of is rejected. This is the same tenant-resolution behavior used across Truestamp’s authenticated HTTP APIs.