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.
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.
Gate a result
Path 2 is Gate: 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 dispute path if the verdict is contested: an evidence window, then an outcome the principal renders and signs.
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 Gate-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 declaratively, applied via POST /v1/admin/provisioning/reload. |
| 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, drift, 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 is 200 per minute per key (RATE_LIMIT_POST_RECORDS). Per-route envs override the per-key budget; the multiplier scales every route uniformly without per-route tuning.
Route families
195 routes across thirteen families
Path counts below; the full operation list lives in the interactive reference at the bottom of this page.
Records - 28 paths. The lifecycle spine. Create, search, batch, bulk; chain and graph walks for delegation; per-record transitions (accept, reject, 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 gate evaluation runs inline in auto mode, and in principal mode runs as an advisory pass before the principal submits the verdict. Examples: POST /v1/records/{id}/completions, GET /v1/records/{id}/completions/{completionId}.
Verdicts - 2 paths. Principal accept/reject on a delivery. accept terminalizes at FULFILLED (or REMEDIATED when overriding a prior reject); reject terminalizes at FAILED. Examples: POST /v1/records/{id}/verdict, GET /v1/records/{id}/gate-status.
Disputes - 6 paths. Either party opens; both submit evidence until the window closes; the record's principal or an org-admin renders the outcome, UPHELD or OVERTURNED, and the initiator can withdraw before that. AGLedger records the outcome; it does not weigh the evidence. Examples: POST /v1/records/{recordId}/dispute, POST /v1/disputes/{id}/resolve.
Federation - 12 paths. Peer-to-peer signed-message transport across Servers. Bilateral handshake, signed state-transitions and signals, co-sign requests, dispute projection, 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. Every new org seeds one editable example type, notarize-generic-v1, and tenant-admins register their own via POST /v1/schemas. Operators can turn the seed off with AGLEDGER_SEED_EXAMPLE_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 Signal payloads, 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 Notify. Examples: POST /v1/webhooks, POST /v1/webhooks/{id}/rotate, GET /v1/webhooks/{id}/deliveries.
Agents and references - 8 paths. Agent profiles, capability declarations (an inventory, not a gate on what a record may ask for), performance history, and drift: what an agent did in the current window, the window before it, and the difference, with no score or threshold. 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}, GET /v1/agents/{agentId}/drift, 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; drift 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}.Predicate profiles
in-toto predicate kinds, schema-discoverable
Every Signed Statement in the chain is a tagged COSE_Sign1 envelope (RFC 9052, tag 18) over a deterministically CBOR-encoded in-toto v1 Statement payload (RFC 8949 §4.2.1). Inside that Statement, the predicateType field tells the verifier which body shape to expect - a URI of the form https://agledger.ai/predicates/{kind}/v1. These are the Predicate Profiles: the in-toto predicate kinds AGLedger itself publishes for how the chain moves, served as JSON Schema.
AGLedger publishes seven first-class predicate kinds. Each corresponds to a distinct event category on the chain. The canonical JSON Schema for every kind is generated from the engine's runtime body shape at module load - drift between published schema and emitted payload is impossible by construction.
| Kind | What it carries |
|---|---|
record-state | Lifecycle transitions on a record (create, accept, complete, fulfill, fail, expire, cancel). |
settlement-signal | SETTLE / HOLD / RELEASE emitted on terminal verdict, with the downstream authorization context. |
vault-checkpoint | Periodic signed checkpoint anchoring vault chain head for external attestation. |
tenant-read | Read attestation - who fetched what, when. Forensic accountability for sensitive lookups. |
counter-attestation | Counterparty co-signed assertion on a federated event - bilateral signal anchor. |
federation-projection | Peer-Server event projected into the local chain so the local audit trail is complete. |
schema-event | Schema registry lifecycle - registration, version bump, lifecycle status change. |
Two unauthenticated discovery endpoints expose the catalog:
GET /predicatesIndex of every kind, its predicate URI, and the schema fetch URL on this deployment.GET /predicates/{kind}/v1The canonical JSON Schema (draft-2019-09) for that kind's predicate body, served as application/schema+json.DSSE bundle exports at /v1/records/{id}/attestation reference these URIs in their predicateType field, so sigstore-compatible tooling can resolve the schema for verification without any AGLedger-specific knowledge.
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 - v1.10.0. Typed wrapper, no framework opinion.pip install agledger - v1.10.0. Matching surface to the TS SDK.npm install -g @agledger/cli - v1.4.0. Scriptable from any shell or CI pipeline.npm install -g @agledger/mcp-server - v2.10.0. Exposes the record lifecycle as MCP tools for Claude Desktop and other MCP hosts.Related capabilities
The lifecycle endpoints behind a Gate - 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.
Author, register, version, and share the contract types that /v1/schemas holds; the predicate kinds above are the ones AGLedger itself publishes.
Full reference
Interactive operation reference
All 195 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.