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. 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 and application version. It is a convenient first call to confirm your credential and connectivity are working before you explore further.

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.

Authentication

Every GraphQL operation requires authentication. 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: a plain GET to /gql/playground is served without authentication so the playground UI itself can load in your browser. The moment you run an operation from the playground, that becomes an authenticated POST and your credential is required just like any other client.

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 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, ulidTimestamp, resolveId, and jcsCanonicalize, mirror the POST /api/json/utilities/* routes; see the utility endpoints reference for their arguments, result shapes, and the visibility gating on resolveId.

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.