> Markdown version of https://agledger.ai/api/
> Full index of this site for AI assistants: https://agledger.ai/llms.txt

# 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](https://www.rfc-editor.org/rfc/rfc9457) 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.

```
# Path 1 - Notarize. Terminalizes at RECORDED in one call.
curl -X POST https://agledger.example.com/v1/records \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type":            "notarize-generic-v1",
    "contractVersion": 1,
    "platform":        "quickstart",
    "criteria": {
      "action":  "draft-q1-report",
      "summary": "Drafted Q1 market analysis"
    }
  }'
```

### Gate a delegated handoff

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 three-tier dispute path if the verdict is contested.

```
# 1. Principal creates the record with autoActivate
curl -X POST https://agledger.example.com/v1/records \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type":             "INVOICE-REVIEW-v1",
    "contractVersion":  1,
    "platform":         "billing",
    "performerAgentId": "<PERFORMER_AGENT_ID>",
    "autoActivate":     true,
    "criteria": { "invoiceId": "INV-2026-0421", "amountUsd": 4250.00 }
  }'

# 2. Performer submits a completion with evidence
curl -X POST https://agledger.example.com/v1/records/{id}/completions \
  -H "Authorization: Bearer $PERFORMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "evidence": { "verdict": "approve", "memo": "matches PO" } }'

# 3. Principal renders verdict; record terminalizes at FULFILLED or FAILED
curl -X POST https://agledger.example.com/v1/records/{id}/verdict \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "verdict": "accept", "completionId": "<UUID>" }'
```

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.

```
{
  "id":     "01HXY...record-uuid",
  "status": "ACTIVE",
  "nextActions": ["submit-completion", "cancel"],
  "validTransitions": ["FULFILLED", "FAILED", "CANCELLED"],
  "suggestion": "Submit completion when the performer is ready.",
  "nextSteps": [
    {
      "action":      "Submit completion",
      "method":      "POST",
      "href":        "/v1/records/{id}/completions",
      "description": "Submit task attestation evidence for gate evaluation",
      "workflowStep":  4,
      "workflowTotal": 5,
      "workflowLabel": "Step 4 of 5: submit completion",
      "afterThis":     "After the completion is accepted, the principal renders accept/reject via POST /verdict."
    },
    {
      "action":      "Check gate status",
      "method":      "GET",
      "href":        "/v1/records/{id}/gate-status",
      "description": "Poll for Phase 2 gate verdict"
    }
  ]
}
```

`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.

```
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
X-Request-ID: 01HXY...

{
  "type":   "/problems/unprocessable-state",
  "title":  "Unprocessable State",
  "status": 422,
  "code":   "UNPROCESSABLE_STATE",
  "detail": "Record is FULFILLED; completions cannot be submitted on a terminal record.",
  "instance":  "/v1/records/01HXY.../completions",
  "currentState":   "FULFILLED",
  "allowedActions": ["view", "export-audit", "open-dispute"],
  "recoveryHint":   "Re-read the resource to see its current state, then choose an action that is valid from that state. The error message names the offending precondition; if the message references a state, treat it as the current ground truth.",
  "retryable":  false,
  "requestId":  "01HXY..."
}
```

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`, `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

## 193 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 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.** 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 [Notify](https://agledger.ai/notify/). 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.

/.well-known/agledger-vault-keys.jsonPublic Ed25519 verification keys plus the sign-input template for offline chain verification. JSON.

/.well-known/scitt-keysCBOR `COSE_KeySet` for SCITT Receipt verification. Per-key entries at `/.well-known/scitt-keys/{kid}`.

/predicatesList of the seven predicate kinds the audit chain attests. Used by verifiers that want to type-check entries before reading them.

/llms.txt · /llms-full.txtAgent-discovery documents. Short form for context budgets, full form for an LLM doing first-touch onboarding. Cached with a flush admin route.

/.well-known/agent-card.jsonA2A AgentCard descriptor - capabilities, JSON-RPC entrypoint, supported skills. For agent hosts that speak the A2A protocol.

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.

TypeScript `npm install @agledger/sdk` - v1.3.3. Typed wrapper, no framework opinion.

Python `pip install agledger` - v1.2.2. Matching surface to the TS SDK.

CLI `npm install -g @agledger/cli` - v1.0.5. Scriptable from any shell or CI pipeline.

MCP server `npm install -g @agledger/mcp-server` - v2.5.5. Exposes the record lifecycle as MCP tools for Claude Desktop and other MCP hosts.

OpenAPI[Download the v1.2.0 OpenAPI 3.0 spec](https://agledger.ai/openapi.json) - generate a client in any language, or feed it to an agent SDK that consumes OpenAPI directly.

Related capabilities

[Gate →](https://agledger.ai/gate/)

The lifecycle endpoints behind a Gate - proposal, acceptance, completion submission, and verdict rendering.

[Federation →](https://agledger.ai/federation/)

The `/federation/v1` routes that carry signed messages between Servers across organizational boundaries.

[Settlement Signals →](https://agledger.ai/settlement-signals/)

The outcome route that projects a SETTLE or HOLD signal to downstream payment, ERP, or ticketing systems.

[Integrations →](https://agledger.ai/integrations/)

Webhook delivery, SIEM export, trace correlation, and the SDKs and MCP server that ride on this API.

[Schemas →](https://agledger.ai/schemas/)

The `/predicates` and `/v1/schemas` discovery routes that publish predicate kinds and contract definitions.

Full reference

## Interactive operation reference

All 193 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](https://agledger.ai/docs/) or the [integrations page](https://agledger.ai/integrations/).