API Reference — Censio

Overview

One API. One MCP. No pipelines to build.

The API does one thing with institutional discipline: it accepts claims and returns Trust Objects — governed, machine-readable records (issued as CensioCert™ certificates) with calibrated confidence, the evidence set, the methodology version and an independently verifiable integrity chain. Five conformant surfaces consume the same objects: this API, the MCP server, the web console, the verify surface and the offline verifier.

# Base URL — all requests over TLS 1.2+
https://api.censio.io/v1
# Sandbox issued alongside your key at onboarding
https://sandbox.api.censio.io/v1
# Live check — public, no key required
curl https://api.censio.io/v1/status

● Gateway · checking…

Status. This reference is the frozen v1 contract for the developer preview, and the gateway is live: /v1/status answers publicly, and every unauthenticated request returns the documented error envelope with a censio-request-id. Endpoint access is enabled per organisation at onboarding, in waitlist order — join the waitlist; credential holders sign in at the onboarding portal. The contract only changes additively; breaking changes require a new major version.

Authentication

Bearer keys, scoped and server-side.

Keys are issued at onboarding, prefixed by scope: ck_read (retrieve & verify), ck_issue (evaluate & monitor). Keys are secrets: server-side only, never in a browser or repository. Rotation is immediate, with a grace window for the outgoing key; every request is attributable to a key and appears in your audit trail.

# Every request
Authorization: Bearer ck_issue_…
Content-Type: application/json

Conventions

The boring guarantees.

Convention	Behaviour
JSON · UTF-8	Request and response bodies are JSON; timestamps are RFC 3339 UTC.
Idempotency-Key	Any POST accepts an Idempotency-Key header (UUID). Retries with the same key return the original result — evaluations are never double-issued.
Request-Id	Every response carries censio-request-id — quote it in support and it appears in your audit trail.
Pagination	Cursor-based: ?limit=…&cursor=…; responses include next_cursor or null.
Determinism	Canonicalisation and fingerprints follow TIP-2 exactly (RFC 8785 → SHA-256) — any conforming implementation reproduces them.

Issue

POST/evaluate

Submit a claim for assessment. The engine grounds it across the evidence network, runs the named methodology, and issues a Trust Object. Synchronous by default; long-running assessments return 202 with an evaluation id to poll.

// Request
{
  "claim": "The counterparty meets its Solvency II reporting obligations for FY2026",
  "methodology": "compliance-model/3.1",
  "context": { "entity_ref": "…", "jurisdiction": "EU" },
  "tier3_sources": ["erp:…"] // optional — your connected private evidence
}

// Response 200 — the Trust Object (TIP-1 schema, abridged)
{
  "tip": "1.0",
  "id": "CX-924837",
  "claim": "The counterparty meets its Solvency II reporting obligations for FY2026",
  "confidence": 0.94,
  "evidence": { "sources": 52, "support": 47, "conflict": 3, "neutral": 2 },
  "methodology": "compliance-model/3.1",
  "issued_at": "2026-07-20T14:02:11Z",
  "version": 12,
  "fingerprint": "sha256:8f4e2b7c…c21a9b7d",
  "anchor": { "epoch": 48213, "root": "b3a1f0…9d47e2", "rails": ["eidas-qts", "public-chain"] }
}

The response never contains a recommendation — Censio measures; you decide against your own policy (see /policy/check).

Retrieve

GET/trust-object/:id

Fetch the current version of a Trust Object by id. Add ?version=n for a historic version — every version remains addressable forever, with the methodology archived under which it was issued (TIP-5).

History

GET/trust-object/:id/history

The full version chain: every issuance, what changed, which methodology version, and each version’s fingerprint and anchor. The chain is append-only — nothing is ever silently rewritten.

Chronology semantics: CDRP — Chronological Decision Replay Protocol™

Verify

POST/verify

Run the TIP-4 walk over an object you hold (or an id): recompute the fingerprint, walk the Merkle inclusion proof to the anchored epoch root, check both rails, confirm the version chain. This endpoint is a convenience — the same walk runs without Censio via the CLI and embed in the launch toolchain, or fully offline from the record alone. That is the point.

// Response 200
{ "verified": true, "fingerprint_match": true, "inclusion_proof": "valid", "rails": { "eidas_qts": "intact", "public_chain": "intact" }, "version_chain": "unbroken" }

Govern

POST/policy/check

Evaluate a Trust Object against your thresholds — minimum confidence, maximum conflict, required methodology, freshness. Returns pass / escalate and issues a governance record, so the decision and its basis are both provable later.

Temporal semantics: TWDP — Time-Weighted Decision Protocol™

// Request
{ "object_id": "CX-924837", "policy": { "min_confidence": 0.90, "max_conflict_ratio": 0.10, "max_age_days": 90 } }

Enforce

POST/mandate

Derive a Mandate from a Trust Object: time-boxed authority to act, bound to your policy and signed (Ed25519). Your systems verify the signature locally, in microseconds — no network call on the hot path. Mandates auto-expire at ttl_seconds and are revoked the instant the underlying object is superseded (see webhooks) — a stale mandate cannot authorise anything.

// Request
{ "object_id": "CX-924837", "policy": { "min_confidence": 0.90, "max_conflict_ratio": 0.10 }, "ttl_seconds": 300 }

// Response 201 — verify locally, act, let it die
{ "mandate": "mnd_…", "object_id": "CX-924837", "policy_hash": "sha256:…", "expires_at": "2026-07-20T14:07:11Z", "signature": "ed25519:…" }

The Sentinel SDK wraps this end to end: shadow mode issues records beside your application without gating anything; mandate mode verifies before actions execute. Every decision — and the mandate it ran under — lands in the Black Box for replay.

Delegation semantics: MWCP — Machine Warrant Chain Protocol™

Monitor

POST/monitor

Subscribe to a claim or object. When the evidence moves and a new version is issued, you receive a supersession webhook — agents re-check via MCP, systems re-run policy. Trust is dynamic; monitoring is how your stack keeps up with it.

Webhooks

Signed, replay-safe, at-least-once.

Event	Fires when
object.superseded	A monitored object is re-issued as a new version.
object.revoked	A terminal supersession — the record stays verifiable, marked revoked.
anchor.confirmed	An epoch root is confirmed on both rails.

Every delivery is signed: censio-signature is an HMAC-SHA256 over the timestamped payload with your endpoint secret; reject deliveries older than 5 minutes to close the replay window. Deliveries are at-least-once — handle idempotently by event id.

Errors

One envelope. Attributable. Actionable.

{ "error": { "code": "policy_violation", "message": "min_confidence 0.90 not met (0.84)", "request_id": "req_…" } }

Code	HTTP	Meaning
invalid_claim	400	The claim is empty, unparseable, or out of scope for the named methodology.
methodology_unknown	400	No published methodology matches the identifier — see the register on /verify.
unauthorized	401	Missing or invalid key.
forbidden_scope	403	The key’s scope does not permit this endpoint.
not_found	404	No Trust Object with that id (ids are never reused, so this is definitive).
rate_limited	429	Over the per-key limit — honour Retry-After.
evaluation_failed	502	The evidence network could not ground the claim; no object is issued and the request is not billed.

Rate limits & versioning

Additive forever, breaking never.

Limits are per key and returned on every response (censio-ratelimit-limit / -remaining / -reset); preview-cohort defaults are sized per organisation at onboarding. The v1 contract changes additively only — new optional fields, never renamed or removed ones. A breaking change means /v2, with v1 maintained through a published sunset window.

MCP

The same contract, agent-native.

The Censio MCP server exposes the reference as tools, one-to-one — agents verify mid-workflow instead of guessing. It is part of the launch toolchain, submitted to the MCP directories on day one.

Tool	Maps to
verify_claim	POST /evaluate → calibrated confidence with cited evidence.
get_trust_object	GET /trust-object/:id
check_policy	POST /policy/check
monitor_claim	POST /monitor + supersession notifications.

Extension family

Six protocols. One discipline.

The v1 contract is the REST binding of TIP. Around it run six extension protocols — all Censio inventions, already operating inside the platform; the long-form names are claimed as trademarks of Censio. Where one underpins a surface of this contract, it is noted on the endpoint and below. The codified family lives in the TIP specification §6.

Protocol	Mark	Touches v1 today
TWDP	Time-Weighted Decision Protocol™	Freshness windows in /policy/check; mandate TTL bounds.
CDRP	Chronological Decision Replay Protocol™	The chronology behind /trust-object/:id/history and the Black Box.
MWCP	Machine Warrant Chain Protocol™	Warrant chains extending POST /mandate delegation.
OWRP	Outcome Witness & Resolution Protocol™	Outcome attestation feeding the published calibration register.
EPCP	Evidence Provenance & Custody Protocol™	Custody records behind every evidence citation (Tier 1–3).
TIFP	Trust Interchange & Federation Protocol™	Cross-issuer interchange, conformance vectors, the issuer registry.