API Documentation | Truestamp

Prefer a command line?

Using your API key, the Truestamp CLI handles creating, downloading, and verifying proofs without writing any API code.

Explore the CLI

Choose Your API

Select an API style to see tailored examples throughout this page.

REST API

Full-service JSON:API compliant interface for CRUD operations, relationships, and filtering.

GraphQL API

Full-service API with flexible queries, introspection, partial responses, and nested relationships.

Feature	REST	GraphQL
Endpoint	`/api/json/items`	`/gql`
Content-Type	`application/vnd.api+json`	`application/json`
Request format	JSON:API envelope	GraphQL mutation
Response format	JSON:API envelope	GraphQL response
Best for	Full-service CRUD, relationships, filtering	Full-service flexible queries, partial responses

Getting Started

1. Generate API Key

All API endpoints require authentication. First, create an account or sign in. Then visit your API keys page to generate an API key. Choose an appropriate expiration time and store the key securely.

Security: Never expose API keys in client-side code or public repositories.

2. Authentication

Include your API key in the request headers:

curl -H "Authorization: Bearer YOUR_API_KEY" \

     -H "Accept: application/vnd.api+json" \

     http://localhost:4000/api/json/items

3. Multi-Tenant Operations

Truestamp supports multi-tenant operations. You can specify a tenant (team) using headers or query parameters:

# Using tenant header

curl -H "Authorization: Bearer YOUR_API_KEY" \

     -H "Accept: application/vnd.api+json" \

     -H "tenant: TEAM_ID" \

     http://localhost:4000/api/json/items

# Using query parameter

curl -H "Authorization: Bearer YOUR_API_KEY" \

     -H "Accept: application/vnd.api+json" \

     "http://localhost:4000/api/json/items?tenant=TEAM_ID"

Automatic Tenant Fallback

If no tenant is specified, operations automatically use your personal team. You must have access to any team you specify in requests.

4. Rate Limiting

All API requests are rate limited. Limits are determined by your account's subscription plan and its entitlements.

Plan	Items / Month	Teams	Members / Team
Free	50	1	1
Starter	750	5	5
Pro	10,000	20	50
Enterprise	100,000	100	500

When a rate limit is exceeded, the API returns a 429 Too Many Requests response. Contact support if you need higher limits.

Core Operations

Timestamping Items

Create cryptographic timestamps for your data:

# Create a new Item via REST API

curl -X POST \

     -H "Authorization: Bearer YOUR_API_KEY" \

     -H "Accept: application/vnd.api+json" \

     -H "Content-Type: application/vnd.api+json" \

     -H "tenant: TEAM_ID" \

     -d '{

       "data": {

         "attributes": {

           "claims": {

             "name": "document.pdf",

             "description": "Important document to timestamp",

             "hash": "98a9396c68596891dabb177924e5604438ae394f42aa651574a653e221f81955",

             "hash_type": "sha256"

     }' \

     http://localhost:4000/api/json/items

Response Formats

Our REST API follows the JSON:API specification for consistent, standardized responses:

"data": {

  "attributes": {

    "state": "created",

    "signature": "5mqfG/XJ8cB3Aopn...E5D68KB9YVDA==",

    "metadata": {

      "previous_block_hash": "4ce272402f4e3e372148c495712ae37e1568d314bce1c38a3ac758c77720c3c8",

      "previous_block_id": "019c5d67-f537-7df2-ab66-3f126c5e4118"

},

    "tags": [],

    "visibility": "private",

    "merkle_proof": null,

    "display_name": "document.pdf",

    "team_id": "019c2a4b-e079-79d8-b305-44144ac61cca",

    "item_hash": "6aacebc6571e4aa68a3b85cd4d73442e97d5ea4de1590d52f4be1d45a04f266b",

    "display_description": "Important document to timestamp",

    "claims": {

      "name": "document.pdf",

      "description": "Important document to timestamp",

      "hash": "98a9396c68596891dabb177924e5604438ae394f42aa651574a653e221f81955",

      "hash_type": "sha256"

},

    "claims_hash": "d1c3628c7050d075806a815b042775490df73ea54c1b6a0660344e5c20a3dfda",

    "metadata_hash": "4f8508a334dcd379043c61bb3268446d99094aec9559d7e04df374355d439712"

},

  "id": "019c5d69-240f-71c4-be75-40684764518f",

  "type": "item",

  "relationships": {

    "block": {},

    "team": {},

    "creator": {}

Documentation & Resources

Interactive Tools

API Reference (ReDoc) API Explorer (Swagger) OpenAPI Spec

Learn More

JSON:API Specification Official spec our REST API follows
JSON:API Examples Request/response patterns
JSON:API Pagination Large result sets are paginated using query parameters
JSON:API Filtering Use query parameters to filter results and reduce payload size

Error Handling

Status Code	Description	Common Causes
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for tenant/resource
`400`	Bad Request	Invalid request format or missing required fields
`422`	Unprocessable Entity	Validation errors in request data
`429`	Too Many Requests	Rate limit exceeded

Support and Resources

Need Help?

Get support for API integration questions and technical issues.

Get Support