Developers

Traces API

Create, manage, seal, and export verifiable proof of entire business processes. Traces group events, documents, and AI attestations into a single sealed, cryptographically proven sequence.

All endpoints require API key authentication via the x-api-key header. Traces are free to create, items within them count against your existing quota.

Lifecycle

POST /traces → POST /events (with trace_id) → POST /traces/:id/seal → GET /traces/:id/proof

The trace_id is server-generated. Your application stores it and references it when anchoring events. Events anchored to a trace are processed identically to standalone events, same hashing, same signing. The trace adds a composite proof layer on top.

Endpoints

POST/traces

Create trace

Create a new open trace. Invoance generates the trace_id. Your application stores it and references it when anchoring events.

label is required (max 255 chars). metadata is optional JSON (max 16 KB).

Request

{
  "label": "Vendor Onboarding, Acme Corp",
  "metadata": {
    "department": "procurement",
    "initiated_by": "j.smith@acme.com"
  }
}

Response

{
  "trace_id": "tr_abc123...",
  "status": "open",
  "created_at": "2026-03-17T12:00:00Z",
  "label": "Vendor Onboarding, Acme Corp"
}

GET/traces

List traces

Paginated list of traces for the authenticated tenant. Filterable by status.

Query params: page (default 1), limit (default 25, max 100), status (open | sealed).

Response

{
  "traces": [
    {
      "trace_id": "tr_abc123...",
      "label": "Vendor Onboarding, Acme Corp",
      "status": "sealed",
      "event_count": 7,
      "created_at": "2026-03-17T12:00:00Z",
      "sealed_at": "2026-03-17T14:30:00Z",
      "composite_hash": "sha256:def456..."
    }
  ],
  "page": 1,
  "limit": 25,
  "total": 12,
  "has_more": false
}

GET/traces/:trace_id

Get trace

Retrieve a single trace with ordered event summaries.

Response

{
  "trace_id": "tr_abc123...",
  "label": "Vendor Onboarding, Acme Corp",
  "status": "sealed",
  "event_count": 7,
  "created_at": "2026-03-17T12:00:00Z",
  "sealed_at": "2026-03-17T14:30:00Z",
  "composite_hash": "sha256:def456...",
  "seal_event_id": "evt_xyz789...",
  "events": [
    {
      "event_id": "evt_001...",
      "event_type": "document.anchored",
      "payload_hash": "sha256:a3f2b1...",
      "ingested_at": "2026-03-17T12:05:00Z"
    }
  ]
}

POST/traces/:trace_id/seal

Seal trace

Initiate sealing. The trace transitions to 'sealing' immediately (blocks new events), then a background worker computes the composite hash, signs the seal event, and transitions to 'sealed'. Returns 202 Accepted.

Sealing is permanent. Once sealed, no events can be added. The trace cannot be reopened. Poll the trace status to confirm completion.

Response

{
  "trace_id": "tr_abc123...",
  "status": "sealing",
  "message": "Seal initiated. Poll GET /traces/:trace_id for completion."
}

GET/traces/:trace_id/proof

Export proof bundle

Returns the complete proof bundle for a sealed trace: every event, document, and AI attestation with full payloads, hashes, and signatures, plus the composite hash, seal event, and verification results. Each AI attestation carries both payload (parsed, for reading) and payload_raw (the verbatim signed bytes) — SHA-256 payload_raw to reproduce payload_hash; do not re-hash payload, since re-serializing can change the bytes. Hashes, signatures, and public keys are lowercase hex.

Only available for sealed traces; returns 409 if still open or sealing. event_count counts events only — item_count is the total across events, documents, and attestations. Empty item arrays are returned as []. Also available as a signed PDF at GET /traces/:trace_id/proof/pdf.

Response

{
  "version": "1.0",
  "trace_id": "76bedccb-94dc-4e2c-95f5-623847457b5b",
  "label": "Vendor Onboarding — Acme Corp",
  "tenant_domain": "acme.com",
  "status": "sealed",
  "source": "api",
  "created_at": "2026-03-17T12:00:00Z",
  "sealed_at": "2026-03-17T14:30:00Z",
  "composite_hash": "65043b6a35c2fb3aefa1017768a7e096...",
  "event_count": 1,
  "item_count": 3,
  "events": [
    {
      "event_id": "d491983d-cf09-4fac-8465-e66af46e9a19",
      "event_type": "approval.recorded",
      "payload": { "approved_by": "m.chen@acme.com" },
      "content_hash": "dfc709253b073bd3f627e5bb2bbe173d...",
      "timestamp": "2026-03-17T12:05:00Z",
      "signature": "8ccee6ed8a0ed99a0f12076ebdbce402...",
      "public_key": "bbfded51a5fdde7fe617469cadeb50d5..."
    }
  ],
  "documents": [
    {
      "document_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "document_ref": "contract_v2.pdf",
      "document_hash": "a94a8fe5ccb19ba61c4c0873d391e987...",
      "event_type": "document.anchored",
      "signature": "6f63d5004af68633ec19879651a23a0b...",
      "public_key": "bbfded51a5fdde7fe617469cadeb50d5...",
      "timestamp": "2026-03-17T12:10:00Z"
    }
  ],
  "attestations": [
    {
      "attestation_id": "26735612-fded-4c73-9f6f-754626f3c2b7",
      "attestation_type": "decision",
      "model_name": "claude-opus-4-8",
      "model_provider": "anthropic",
      "payload": { "type": "decision", "payload": { "output": "PASS" } },
      "payload_raw": "{"type":"decision","payload":{"output":"PASS"}}",
      "payload_hash": "5d036ab3cd096759c4817171ce713ed6...",
      "signature": "519275ccb6fee55be967f599d6838bfe...",
      "public_key": "bbfded51a5fdde7fe617469cadeb50d5...",
      "timestamp": "2026-03-17T12:15:00Z"
    }
  ],
  "seal_event": {
    "event_id": "a60cf139-48fe-4e28-a0d5-e731d7c04b59",
    "event_type": "trace.sealed",
    "content_hash": "d98e08a94e787a5560eb43a6093c4ded...",
    "timestamp": "2026-03-17T14:30:00Z",
    "signature": "d8ab403f1c84c88c6d35286a50bd7506...",
    "public_key": "bbfded51a5fdde7fe617469cadeb50d5..."
  },
  "verification": {
    "composite_hash_valid": true,
    "all_signatures_valid": true
  }
}

Anchoring items to a trace

Pass the optional trace_id field to any ingest endpoint, events, documents, or AI attestations. Each item is processed identically to its standalone counterpart (same hashing, same signing). The trace_id is a grouping reference, not part of the content hash.

POST /events

{
  "event_type": "approval.recorded",
  "trace_id": "tr_abc123...",
  "payload": { ... }
}

POST /document/anchor

{
  "document_hash": "a94a8f...",
  "trace_id": "tr_abc123...",
  "document_ref": "contract.pdf"
}

POST /ai/attestations

{
  "type": "output",
  "trace_id": "tr_abc123...",
  "payload": { ... }
}

Validation: trace must exist, belong to the same tenant, and have status "open". Returns 404 if trace not found, 409 if trace is sealed or sealing. A single trace can contain any mix of events, documents, and attestations.

SDK reference

The full per-method Traces SDK reference — create, add items, seal, export proof (JSON & PDF), list, get, and delete — in all eight languages.

View the Traces SDK reference

Error codes

404trace_not_foundTrace ID does not exist or does not belong to this tenant.

409trace_sealedTrace is already sealed. No items can be added.

409trace_sealingTrace is currently being sealed. Try again after seal completes.

400empty_traceTrace has no items. A trace must contain at least one event, document, or attestation to be sealed.

400invalid_labelLabel is required and must be <= 255 characters.

400metadata_too_largeMetadata exceeds 16 KB limit.

Traces product page

Full product overview with lifecycle, proof bundles, and use cases.

SDK reference

client.traces.create(), .seal(), .proof(), Python, Node.js, Go, Java, Ruby, Rust, .NET, PHP, cURL.

{ "traces": [ { "trace_id": "tr_abc123...", "label": "Vendor Onboarding, Acme Corp", "status": "sealed", "event_count": 7, "created_at": "2026-03-17T12:00:00Z", "sealed_at": "2026-03-17T14:30:00Z", "composite_hash": "sha256:def456..." } ], "page": 1, "limit": 25, "total": 12, "has_more": false }

{ "trace_id": "tr_abc123...", "label": "Vendor Onboarding, Acme Corp", "status": "sealed", "event_count": 7, "created_at": "2026-03-17T12:00:00Z", "sealed_at": "2026-03-17T14:30:00Z", "composite_hash": "sha256:def456...", "seal_event_id": "evt_xyz789...", "events": [ { "event_id": "evt_001...", "event_type": "document.anchored", "payload_hash": "sha256:a3f2b1...", "ingested_at": "2026-03-17T12:05:00Z" } ] }

{ "version": "1.0", "trace_id": "76bedccb-94dc-4e2c-95f5-623847457b5b", "label": "Vendor Onboarding — Acme Corp", "tenant_domain": "acme.com", "status": "sealed", "source": "api", "created_at": "2026-03-17T12:00:00Z", "sealed_at": "2026-03-17T14:30:00Z", "composite_hash": "65043b6a35c2fb3aefa1017768a7e096...", "event_count": 1, "item_count": 3, "events": [ { "event_id": "d491983d-cf09-4fac-8465-e66af46e9a19", "event_type": "approval.recorded", "payload": { "approved_by": "m.chen@acme.com" }, "content_hash": "dfc709253b073bd3f627e5bb2bbe173d...", "timestamp": "2026-03-17T12:05:00Z", "signature": "8ccee6ed8a0ed99a0f12076ebdbce402...", "public_key": "bbfded51a5fdde7fe617469cadeb50d5..." } ], "documents": [ { "document_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "document_ref": "contract_v2.pdf", "document_hash": "a94a8fe5ccb19ba61c4c0873d391e987...", "event_type": "document.anchored", "signature": "6f63d5004af68633ec19879651a23a0b...", "public_key": "bbfded51a5fdde7fe617469cadeb50d5...", "timestamp": "2026-03-17T12:10:00Z" } ], "attestations": [ { "attestation_id": "26735612-fded-4c73-9f6f-754626f3c2b7", "attestation_type": "decision", "model_name": "claude-opus-4-8", "model_provider": "anthropic", "payload": { "type": "decision", "payload": { "output": "PASS" } }, "payload_raw": "{"type":"decision","payload":{"output":"PASS"}}", "payload_hash": "5d036ab3cd096759c4817171ce713ed6...", "signature": "519275ccb6fee55be967f599d6838bfe...", "public_key": "bbfded51a5fdde7fe617469cadeb50d5...", "timestamp": "2026-03-17T12:15:00Z" } ], "seal_event": { "event_id": "a60cf139-48fe-4e28-a0d5-e731d7c04b59", "event_type": "trace.sealed", "content_hash": "d98e08a94e787a5560eb43a6093c4ded...", "timestamp": "2026-03-17T14:30:00Z", "signature": "d8ab403f1c84c88c6d35286a50bd7506...", "public_key": "bbfded51a5fdde7fe617469cadeb50d5..." }, "verification": { "composite_hash_valid": true, "all_signatures_valid": true } }