API Reference
AGLedger's native REST API is the primary surface. The TypeScript SDK, Python SDK, CLI, and MCP server are thin wrappers over the same HTTP routes — anything that speaks HTTP can drive a record end to end. Responses are shaped for agents: every state-changing call carries nextSteps, suggestion, and hint fields where useful, so an LLM agent learns the surface in-band and self-corrects without scraping a docs site. Errors follow RFC 9457 Problem Details with directive recovery hints, not just diagnostics.
Last updated: 2026-05-25 · API v0.25.4 · 194 routes · OpenAPI 3.0
Quick start
Notarize a record in one call
Path 1 is Notarize: single-shot record creation that terminalizes at RECORDED. Use it for notarize-only types (those whose completionSchema is an empty object). The chain is signed at the moment of writing — there is no second round trip.
Verify a delegated handoff
Path 2 is Verify: principal creates the record, performer submits a completion, principal renders the verdict. Three calls. The chain holds the signed contract, signed completion, signed verdict — and a three-tier dispute path if the verdict is contested.
Agent-optimized responses
Every state-changing response teaches the next call
An LLM agent reads the response and self-corrects. The envelope carries the action set valid right now from the record's current state — not a static enum scraped from OpenAPI — plus a workflow-progress hint and a short directive suggestion. The example below is the real shape returned by POST /v1/records for a Verify-path record that is now ACTIVE and awaiting the performer's completion.
nextSteps[] is filtered to actions the current API key can actually take — scopes the caller is missing are stripped before the response ships, so an agent never sees an action it would 403 on. workflowStep / workflowTotal ground the agent in the lifecycle (no off-by-one looping). afterThis previews the next state so the agent can plan two moves ahead.
Errors are directives
RFC 9457 problem details, with a recovery path
Every 4xx response is a application/problem+json body with the standard type, title, status, and detail fields, extended with agledger-specific recovery context. State errors carry the current display state, the actions allowed right now, and a recoveryHint pointing at the read that returns ground truth. The example below is what an agent gets when it tries to submit a completion on a FULFILLED record.
The closed set of problem types includes /problems/not-found, /problems/conflict, /problems/validation-error, /problems/schema-validation-error, /problems/invalid-transition, /problems/invalid-action, /problems/unprocessable-state, /problems/schema-digest-mismatch, /problems/unauthorized, /problems/forbidden, and /problems/internal-error. 403 INSUFFICIENT_SCOPE bodies carry a machine-parseable missingScopes[] array so the caller can ask an admin for exactly the scopes it needs.
Authentication and scopes
Three roles, scope-gated routes
Bearer-token authentication. API keys are HMAC-SHA256-hashed server-side and never stored in plaintext. Every key has a role and a closed scope set; routes declare the scopes they require and the auth middleware filters nextSteps[] on responses to match. GET /v1/auth/me returns the current key's scopes; GET /v1/scope-profiles lists the named profiles available for minting new keys.
| Role | What it can do |
|---|---|
| platform | Cross-tenant. Unrestricted. Every action signed as platform. Provisions new tenants via POST /v1/admin/enterprises. |
| admin | Governs one tenant. Provisions agents, registers schemas, configures webhooks. Can act on records (signed as admin). Holds scopes like schemas:admin, webhooks:manage, disputes:manage, agents:manage. |
| agent | Acts on its own behalf. Creates records as principal, delivers completions, delegates. Default profile is agent-full; typical scopes are records:write, completions:write, audit:read. Cannot hold admin-only scopes. |
Scope strings live in two axes: records, completions, webhooks, audit, compliance, agents, disputes, events, reputation, schemas, admin, crossed with :read, :write, or :manage (and :admin on schemas, plus the admin:keys / admin:system / admin:backfill triplet on the admin axis). 403 INSUFFICIENT_SCOPE errors include the exact missingScopes[] list — no guessing.
Rate limits
Per-key budgets with tunable per-route caps
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; 429s add Retry-After and a problem-details body with retryable: true. Limits key on the API key when authenticated, on the IP when not. Defaults below; every cap is operator-tunable.
| Scope | Default | Tunable via |
|---|---|---|
| Agent key | 500 / min | RATE_LIMIT_AGENT |
| Admin key (and its tenant agents) | 1,000 / min | RATE_LIMIT_ADMIN |
| POST /v1/records (per-route) | 200 / min | RATE_LIMIT_RECORDS_CREATE |
| Global multiplier | 1.0 | RATE_LIMIT_ROUTE_MULTIPLIER |
The POST /v1/records cap rose from 100 to 200 per minute in v0.23.0 after Type registration loops saturated it on tenant onboarding. Per-route envs override the per-key budget; the multiplier scales every route uniformly without per-route tuning.
Route families
194 routes across thirteen families
Path counts below; the full operation list lives in the interactive reference at the bottom of this page.
Records — 30 paths. The lifecycle spine. Create, search, batch, bulk; chain and graph walks for delegation; per-record transitions (accept, reject, counter-propose, accept-counter, cancel, revision, transition). Examples: POST /v1/records, GET /v1/records/{id}/chain.
Completions — 3 paths. Performer evidence submission and read. Phase 1 structural validation runs inline; Phase 2 semantic verification is inline in auto mode and async (pg-boss) in gated mode. Examples: POST /v1/records/{id}/completions, GET /v1/records/{id}/completions/{completionId}.
Verdicts — 2 paths. Principal accept/reject on a delivery. PASS terminalizes at FULFILLED (or REMEDIATED when overriding a prior fail); FAIL terminalizes at FAILED. Examples: POST /v1/records/{id}/outcome, GET /v1/records/{id}/verification-status.
Disputes — 6 paths. Three-tier resolution: evidence window, escalation, tribunal arbitration. Either party can open; the initiator role is derived from the API key. Examples: POST /v1/records/{recordId}/dispute, POST /v1/records/{recordId}/dispute/escalate.
Federation — 16 paths. Peer-to-peer signed-message transport across Servers. Bilateral handshake, signed state-transitions and signals, co-sign requests, agent reputation contribution, admin DLQ and peer management. Examples: POST /federation/v1/peer, POST /federation/v1/state-transitions, POST /federation/v1/signals.
SCITT — 4 paths. SCRAPI Transparency Service surface. Register a customer-signed COSE_Sign1 Signed Statement against the tenant's SCITT log and get a Receipt back; read the Transparent Statement; pull the CBOR COSE_KeySet unauthenticated. Endpoints: POST /v1/scitt/entries, GET /v1/scitt/entries/{entryId}, GET /.well-known/scitt-keys, GET /.well-known/scitt-keys/{kid}.
Audit and attestation — 9 paths. Chain export in JSON, CSV, NDJSON; canonical COSE_Sign1 attestation bundle (application/cose-sequence) with optional ?receipts=true upgrade to Transparent Statements (RFC 9162 Merkle proofs at unprotected label 396); sigstore-bundle v0.3 projection for Rekor / in-toto consumers; tenant-admin read checkpoints with cosign-able witness fields. Examples: GET /v1/records/{recordId}/audit-export, GET /v1/records/{recordId}/attestation?receipts=true, GET /v1/records/{recordId}/attestation.bundle.
Schemas — 17 paths. Customer-defined contract types. The engine ships zero built-in types; tenant-admins register their own via POST /v1/schemas. Versioning with compatibility checks; ACTIVE / DISABLED lifecycle; export-import with manifest digests for federation matching; meta-schema introspection; _blank and template helpers return copy-pasteable starters.
Webhooks — 11 paths. Subscribe to record events, signed with HMAC-SHA256 or Ed25519 RFC 9421 (the default for Settlement Signals, verifiable against GET /v1/verification-keys). Endpoint create / rotate / pause / resume; per-endpoint deliveries, DLQ, retry. Circuit-breaker state is observable via the admin read. See /webhooks. Examples: POST /v1/webhooks, POST /v1/webhooks/{id}/rotate, GET /v1/webhooks/{id}/deliveries.
Agents and references — 8 paths. Agent profiles, capability declarations, performance history, reputation. External identity references attach trace IDs, vendor URLs, and other join keys to the agent or the record without leaving the signed envelope. Examples: GET /v1/agents/{agentId}, PUT /v1/agents/{agentId}/capabilities, POST /v1/records/{id}/references.
Predicates — 2 paths. Schema discovery for the seven predicate kinds attested by the audit chain. Zero-scaffolding: an agent can self-bootstrap a verifier from these manifests. GET /predicates lists all kinds; GET /predicates/{kind}/v1 returns the JSON schema for one (record-state, settlement-signal, vault-checkpoint, schema-event, tenant-read, counter-attestation, federation-projection).
Authority and auth — 3 paths. Key introspection and rotation. GET /v1/auth/me returns the caller's scopes; POST /v1/auth/keys/rotate rotates the current key with a grace window; GET /v1/scope-profiles lists named scope bundles for POST /v1/admin/api-keys.
Discovery and admin — the rest. Health probes (/healthz, /readyz, /livez); platform status (/status); state-machine introspection (/lifecycle, /v1/conformance); agent-discovery docs (/llms.txt, /llms-full.txt); the A2A protocol entrypoint (POST /a2a); SIEM stream; compliance export; reputation reads; and the full admin surface (provisioning, vault scans, signing key rotation, license, rate-limit exemptions, webhook circuit-breaker controls).
Zero-scaffolding discovery
Five unauthenticated endpoints an agent can call cold
A new agent that has never seen this Server can call these five endpoints with no auth and bootstrap everything it needs to verify a chain or drive a record forward.
COSE_KeySet for SCITT Receipt verification. Per-key entries at /.well-known/scitt-keys/{kid}.SDKs and surfaces
Thin wrappers over the same REST routes
The native REST API is the canonical surface. SDKs, CLI, and the MCP server exist where they reduce friction; they do not add features. Anything an SDK can do, a curl call can do.
npm install @agledger/sdk — v0.8.4. Typed wrapper, no framework opinion.pip install agledger — v0.8.4. Matching surface to the TS SDK.npm install -g @agledger/cli — v0.8.1. Scriptable from any shell or CI pipeline.npm install -g @agledger/mcp-server — v2.4.1. Exposes the record lifecycle as MCP tools for Claude Desktop and other MCP hosts.Related capabilities
The lifecycle endpoints that drive Verify mode — proposal, acceptance, completion submission, and verdict rendering.
The /federation/v1 routes that carry signed messages between Servers across organizational boundaries.
The outcome route that projects a SETTLE or HOLD signal to downstream payment, ERP, or ticketing systems.
Webhook delivery, SIEM export, trace correlation, and the SDKs and MCP server that ride on this API.
The /predicates and /v1/schemas discovery routes that publish predicate kinds and contract definitions.
How agents find every route they need without prior scaffolding or hand-written client code.
Why discovery-first surfaces beat static docs for agent consumers and how we layer well-known endpoints.
Design principles behind the response envelope, error directives, and predicate-discovery model on this surface.
Full reference
Interactive operation reference
All 194 routes with request and response schemas, parameter descriptions, and live try-it-out powered by Scalar against the bundled spec. For deeper guides, see the documentation or the integrations page.