{ "openapi": "3.0.3", "info": { "title": "AGLedger API", "description": "AGLedger is a self-hosted cryptographic notary for automated work — built for audit, governance, and org scale.\n\nAGLedger records what AI agents are authorized to do, how they delegate, and what they report back. Every authorization, delegation, and completion is captured in a cryptographically signed, tamper-evident Audit Chain (SHA-256 hash chain with optional Ed25519 per-entry signatures over RFC 8785 JCS canonical JSON). When an incident occurs, the full decision chain is reconstructable.\n\nThe **Compliance Export** assembles org-wide audit data for regulators, auditors, and GRC tooling.\n\n**Key capabilities:** customer-defined Types via `POST /v1/schemas` (the engine ships zero built-in types — register your own), an 11-state customer-facing record lifecycle, delegation chains (default depth 5, configurable up to 10) with cascading gates, A2A protocol support (AgentCard discovery + JSON-RPC 2.0), dual operating modes (cleartext where the server can evaluate gates, encrypted where the principal evaluates), three-tier dispute resolution, and agent reputation scores.\n\n## Authentication\n\nAll authenticated endpoints require a Bearer token in the `Authorization` header. API keys are hashed with HMAC-SHA256 server-side and never stored in plaintext. Three roles exist:\n\n- **admin** -- governs a org: provisions agents, manages schemas/webhooks/policy, can act on records (signed as admin)\n- **agent** -- acts: creates records as principal by default, delivers completions, delegates\n- **platform** -- cross-org; unrestricted; every action signed as platform\n\nAGLedger is self-hosted only. Accounts are provisioned by an operator via `POST /v1/admin/orgs` + `POST /v1/admin/api-keys` (or via the `provisioning/` YAML config-as-code directory).\n\nPublic endpoints (`/health`, `/docs/*`, `/schemas/*`) do not require authentication. Protocol endpoints (`/.well-known/*`, `/a2a`) are also at root. All business routes are under `/v1`.\n\n## Webhook Signatures\n\nA subscription is signed with one of two schemes, fixed at create time via `signingAlg` and reported on every response. You receive an asymmetric RFC 9421 signature iff the subscription was created with an asymmetric `signingAlg` (`ed25519`, or `ecdsa-p256-sha256` on a Server opted into ES256; the value must match the active vault key) or is a settlement subscription on a key-bearing Server; otherwise `hmac`.\n\n**`hmac` (default).** HMAC-SHA256 with the per-subscription shared secret:\n\n```\nX-AGLedger-Signature: t=,v1=\n```\n\nThe signed input is `.` — the literal `t=` is a parser prefix, NOT part of the HMAC input. Recompute the HMAC over `${timestamp}.${rawBody}` with your secret and compare constant-time. Reject deliveries where `t` is more than 300 seconds old (replay protection). Right for the private, receiver-only case.\n\n**Asymmetric (opt-in, non-repudiable).** RFC 9421 HTTP Message Signatures signed with the Server vault key — the receiver holds no secret and verifies against the published public key, so a Settlement Signal is provable to a third party (the same trust root as the chain). The wire `alg` parameter is the active key's RFC 9421 name (`ed25519` by default). Headers:\n\n```\nContent-Digest: sha-256=::\nSignature-Input: sig1=(\"content-digest\" \"x-agledger-idempotency-key\");created=;keyid=\"\";alg=\"\"\nSignature: sig1=::\n```\n\nVerify with any RFC 9421 library (e.g. the `http-message-signatures` package): resolve `keyid` against `GET /v1/verification-keys` (feed `publicKey`, the SPKI-DER form RFC 9421 libraries expect; `publicKeyRaw` is the raw 32-byte form for raw-key libraries like libsodium), check the signature over the RFC 9421 signature base, and enforce the `created` 300s replay window. No derived components (`@method`/`@target-uri`) are signed, so proxy/LB rewrites do not break verification.\n\nDedup on the `X-AGLedger-Idempotency-Key: ` header — the event id, stable across retries (and, for asymmetric subscriptions, covered by the signature). The `X-AGLedger-Delivery: ` header is a per-attempt correlation id and changes on each retry, so do not dedup on it.\n\n## Rate Limiting\n\nAll responses include rate limit headers:\n\n| Header | Description |\n|---|---|\n| `X-RateLimit-Limit` | Maximum requests allowed in the current window (1 minute) |\n| `X-RateLimit-Remaining` | Requests remaining in the current window |\n| `X-RateLimit-Reset` | Seconds until the window resets |\n| `Retry-After` | Seconds to wait before retrying (429 responses only) |\n\nRate limits vary by role: agents get 500 req/min, admin keys (and their org agents) get 1,000 req/min. Defaults are tunable via `RATE_LIMIT_AGENT` / `RATE_LIMIT_ADMIN` env vars. Rate limiting is keyed by API key when authenticated, falling back to IP address.\n\n## Request Correlation (`X-Request-ID`)\n\nClients may send an `X-Request-ID` header (max 128 characters, alphanumeric plus hyphens) on any request for end-to-end correlation. The server echoes the same value back on the response. If the header is not provided, the server generates a UUID automatically. This header is present on **all** responses.\n\n## Standard Response Headers\n\nEvery authenticated response includes the following headers (see `standardResponseHeaders` in the SDK/schema definitions):\n\n| Header | Description |\n|---|---|\n| `X-Request-ID` | Request correlation ID — echoed from request or server-generated UUID |\n| `X-RateLimit-Limit` | Maximum requests allowed per window |\n| `X-RateLimit-Remaining` | Remaining requests in current window |\n| `X-RateLimit-Reset` | Seconds until rate limit window resets |\n\n## Idempotency\n\nSupported on POST endpoints that accept the `Idempotency-Key` header (max 256 characters). When present, the server returns the cached response for duplicate keys within a 24-hour window.", "version": "1.4.0", "contact": { "name": "AGLedger", "url": "https://agledger.ai" }, "license": { "name": "Proprietary" } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key for admin, agent, or platform roles. Include as `Bearer ` in the Authorization header." }, "platformAuth": { "type": "http", "scheme": "bearer", "description": "Platform-role API key (`agl_plt_*`). Required for `/v1/admin/*` endpoints." }, "adminOidcJwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OIDC JWT issued by an IdP registered in `trusted_issuers` with `appliesTo: admin`. Customer's Okta/Azure AD/Auth0/Keycloak issues the JWT directly; AGLedger does NOT mint anything. Required claims: `iss` + `aud` matching the registered row, plus the IdP claim that the row's `claimMapping.role` points at (value must resolve to `platform`/`admin`/`org`). Validation runs every request (JWKS-cached). See GET /llms.txt → \"OIDC Workload Identity → Mode 1\"." }, "agentEphemeralCert": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "AGLedger-issued ephemeral cert JWS (`POST /v1/auth/oidc/cert` mints it from an IdP JWT). Short-lived (cert TTL = min(now + maxCredentialTtlSeconds, jwt.exp); 10-min cap by default, 60s floor — sub-60s remaining JWT exp returns 422 instead of issuing a cert). Optional companion: X-Agent-Signature + X-Agent-Signature-Content-Hash for per-request co-signature. See GET /llms.txt → \"OIDC Workload Identity → Mode 2 — Agent ephemeral cert\"." }, "federationPeerSignature": { "type": "apiKey", "in": "header", "name": "X-AGLedger-Signature", "description": "V1 per-request Ed25519 signature in the `X-AGLedger-*` header set (Peer-Hub-Id, Timestamp, Nonce, Signature). Signature covers the sign-input `agledger.federation.v1:METHOD:PATH:bodyHash:timestamp:nonce` and is verified against the peer Server's published signing key. No bearer tokens — every request stands on its own signature." } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "type": { "type": "string", "description": "URI reference identifying the problem type (RFC 9457)" }, "title": { "type": "string", "description": "Short human-readable summary of the problem type (RFC 9457)" }, "status": { "type": "integer", "description": "HTTP status code (RFC 9457)" }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence (RFC 9457)" }, "instance": { "type": "string", "description": "URI reference identifying the specific occurrence (RFC 9457)" }, "errors": { "type": [ "null", "array" ], "items": { "type": "object", "additionalProperties": true }, "description": "Structured validation errors (RFC 9457 extension, present on 400 responses)" }, "retryable": { "type": "boolean", "description": "Whether the client should retry this request (true for 429, 5xx; false for 4xx)" }, "error": { "type": "string", "description": "Machine-readable error code (e.g., NOT_FOUND, VALIDATION_ERROR, FORBIDDEN)" }, "message": { "type": "string", "description": "Human-readable error description" }, "requestId": { "type": "string", "description": "Unique request identifier for support correlation" }, "details": { "type": [ "null", "array" ], "items": { "type": "object", "additionalProperties": true }, "description": "Validation error details (present on 400/422 responses)" }, "suggestion": { "type": "string", "description": "Suggested correction when a field-name typo is detected (e.g., \"Body contains 'type' — did you mean 'type'?\")" }, "recoveryHint": { "type": "string", "description": "Machine-readable recovery guidance pointing to relevant endpoints (e.g., schema lookup URL)" }, "missingFeatures": { "type": "array", "items": { "type": "string" }, "description": "License features required but not available at the current tier" }, "currentTier": { "type": "string", "description": "Current license tier (developer, org)" }, "requiredTier": { "type": "string", "description": "Minimum tier required for the missing features" }, "nextSteps": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Guided next actions for AI agents and integrations" }, "missingScopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes required but not present" }, "hint": { "type": "string", "description": "Contextual hint for record/completion validation (e.g., schema lookup URL)" }, "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required fields for the request body (present on 400 for record/completion creation)" }, "optionalFields": { "type": "array", "items": { "type": "string" }, "description": "Optional fields for the request body (present on 400 for record/completion creation)" }, "examplePayload": { "type": "object", "additionalProperties": true, "description": "Example request body for record/completion creation" }, "schemaUrl": { "type": "string", "description": "URL to the type schema for field reference" }, "recordType": { "type": "string", "description": "Record Type (formerly Contract Type) related to the validation error" }, "currentState": { "type": "string", "description": "Current state of the resource" }, "attemptedTransition": { "type": "string", "description": "Transition that was attempted" }, "attemptedState": { "type": "string", "description": "State the caller asked the resource to move to (federation: POST /federation/v1/state-transitions terminal-conflict 422 carries this alongside `currentState`)." }, "validTransitions": { "type": "array", "items": { "type": "string" }, "description": "Valid transitions from the current state" }, "attemptedAction": { "type": "string", "description": "The /transition action name that was submitted" }, "allowedActions": { "type": "array", "items": { "type": "string" }, "description": "Action names accepted by POST /v1/records/{id}/transition in the current state" }, "refreshUrl": { "type": "string", "description": "Concrete GET URL the agent should re-fetch to read fresh nextActions/validTransitions/allowedActions (set on 422 INVALID_ACTION when the request path includes a record id)." }, "allowedValues": { "type": "array", "items": {}, "description": "Permitted values for the field that failed an enum constraint, or the registered list when the rejection is a \"no such X\" lookup (e.g., unknown type → registered types)." }, "disputeCount": { "type": "integer", "description": "Number of disputes already filed against this record (open + terminal). Surfaced on 422 when the dispute cap is hit." }, "maxDisputes": { "type": "integer", "description": "Maximum disputes allowed on this record (default 1). Surfaced alongside disputeCount when the cap is hit." }, "openDisputeId": { "type": [ "null", "string" ], "format": "uuid", "description": "ID of the currently-open dispute (EVIDENCE_WINDOW or TIER_2_REVIEW). Null when all prior disputes have terminalized. Surfaced on 422 when the dispute cap is hit so the agent can escalate the existing one rather than try to open another." }, "currentStatus": { "type": "string", "description": "Display status of the record at the moment the request was refused. Surfaced on 422 when a dispute is attempted while verification is still in progress." }, "disputeableWhen": { "type": "array", "items": { "type": "string" }, "description": "Display statuses from which POST /v1/records/{recordId}/dispute is accepted. Poll GET /v1/records/{recordId} until status is one of these, then retry." }, "allowedActors": { "type": "array", "items": { "type": "string" }, "description": "Role/actor labels permitted for this action in the current resource state. Surfaced on 403 cross-tier rejections (e.g., parent-principal trying to act on a sub-record it is not direct-principal of)." }, "parentRecordId": { "type": "string", "format": "uuid", "description": "ID of the parent record that rejected the delegation attempt. Surfaced on 422 when the parent state cannot accept children." }, "reason": { "type": "string", "description": "Machine-readable reason code. On 409 conflicts: STATUS_NOT_DISABLED, RECORDS_REFERENCE_TYPE, CONFLICTING_VERSION, RESERVED_PUBLISHER_LABEL, VAULT_SCAN_IN_FLIGHT. On 422 authority-guard refusals: the snake_case guard identifier (has_children_leaf_only, leaf_record, no_children, children_not_terminal, mode_not_auto, mode_not_principal, record_disputed). Branch on this rather than on the prose in `detail`." }, "jobId": { "type": "string", "format": "uuid", "description": "ID of the background job this request is being refused in favour of. Poll GET /v1/admin/vault/scan/{jobId} for its state and result. Present on 409 VAULT_SCAN_IN_FLIGHT." }, "publisher": { "type": "string", "description": "Publisher label on the conflicting schema row." }, "version": { "type": "string", "description": "Manifest version string on the conflicting schema row." }, "incomingDigest": { "type": "string", "description": "sha256: digest of the manifest the caller just submitted." }, "existingDigest": { "type": "string", "description": "sha256: digest of the manifest already registered at this (publisher, type, version)." }, "publishers": { "type": "array", "items": { "type": "string" }, "description": "Candidate publisher labels on a 422 `/problems/ambiguous-publisher`. Emitted by /v1/schemas/{type} reads and writes (pin with `?publisher=`) and by record creation (pin with a `publisher` body field)." }, "pinnedRecords": { "type": "integer", "description": "Records written against the exact registration this delete would remove." }, "unattributableRecords": { "type": "integer", "description": "Records of this type carrying no registration pin, so they block a delete under any publisher label." }, "peerDigest": { "type": "string", "description": "sha256: digest the federation peer claimed in `schemaRef.manifestDigest`." }, "localDigest": { "type": "string", "description": "sha256: digest the receiver holds locally for the same (publisher, type, version, org) tuple." }, "revisionCount": { "type": "integer", "description": "Number of revisions consumed at the moment OVERFLOW_REJECT fired." }, "maxRevisions": { "type": "integer", "description": "Configured maxRevisions cap on the record." }, "terminalReason": { "type": "string", "description": "Machine-readable label naming the system action that terminalized the record (e.g. OVERFLOW_REJECT, ARBITRATION_LOCK, TIME_OUT)." }, "deadline": { "type": "string", "format": "date-time", "description": "The record deadline that had already passed when the request was refused (system TIME_OUT)." }, "previousStatus": { "type": "string", "description": "Display status the record was at immediately before the terminal transition." }, "constraintViolations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Constraint violations for the request" }, "constraint": { "type": "string", "description": "Database constraint that was violated" }, "validationErrors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Schema validation errors" }, "migratedTo": { "type": "string", "description": "Suggested replacement path for a renamed endpoint. Present on 404 responses for routes retired in a migration (e.g. /v1/admin/enterprises → /v1/admin/orgs)." }, "expected": { "type": "string", "description": "Expected JSON type or value, paired with `received` on validation errors." }, "signInputTemplate": { "type": "string", "description": "Exact byte template the Ed25519 proof-of-possession signature must cover, with the domain prefix. Surfaced on the federation 401 for an invalid signature." }, "docs": { "type": "string", "description": "Pointer to the discovery document section describing the failed scheme (e.g. \"/llms.txt (Federation Signing Scheme section)\"). Paired with signInputTemplate + hint on the federation 401." } }, "additionalProperties": false }, "RateLimitError": { "type": "object", "properties": { "type": { "type": "string", "description": "URI reference identifying the problem type (RFC 9457)" }, "title": { "type": "string", "description": "Short human-readable summary of the problem type (RFC 9457)" }, "status": { "type": "integer", "description": "HTTP status code (RFC 9457)" }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence (RFC 9457)" }, "instance": { "type": "string", "description": "URI reference identifying the specific occurrence (RFC 9457)" }, "errors": { "type": [ "null", "array" ], "items": { "type": "object", "additionalProperties": true }, "description": "Structured validation errors (RFC 9457 extension, present on 400 responses)" }, "retryable": { "type": "boolean", "description": "Whether the client should retry this request (true for 429, 5xx; false for 4xx)" }, "error": { "type": "string", "description": "Machine-readable error code (e.g., NOT_FOUND, VALIDATION_ERROR, FORBIDDEN)" }, "message": { "type": "string", "description": "Human-readable error description" }, "requestId": { "type": "string", "description": "Unique request identifier for support correlation" }, "details": { "type": [ "null", "array" ], "items": { "type": "object", "additionalProperties": true }, "description": "Validation error details (present on 400/422 responses)" }, "suggestion": { "type": "string", "description": "Suggested correction when a field-name typo is detected (e.g., \"Body contains 'type' — did you mean 'type'?\")" }, "recoveryHint": { "type": "string", "description": "Machine-readable recovery guidance pointing to relevant endpoints (e.g., schema lookup URL)" }, "missingFeatures": { "type": "array", "items": { "type": "string" }, "description": "License features required but not available at the current tier" }, "currentTier": { "type": "string", "description": "Current license tier (developer, org)" }, "requiredTier": { "type": "string", "description": "Minimum tier required for the missing features" }, "nextSteps": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Guided next actions for AI agents and integrations" }, "missingScopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes required but not present" }, "hint": { "type": "string", "description": "Contextual hint for record/completion validation (e.g., schema lookup URL)" }, "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required fields for the request body (present on 400 for record/completion creation)" }, "optionalFields": { "type": "array", "items": { "type": "string" }, "description": "Optional fields for the request body (present on 400 for record/completion creation)" }, "examplePayload": { "type": "object", "additionalProperties": true, "description": "Example request body for record/completion creation" }, "schemaUrl": { "type": "string", "description": "URL to the type schema for field reference" }, "recordType": { "type": "string", "description": "Record Type (formerly Contract Type) related to the validation error" }, "currentState": { "type": "string", "description": "Current state of the resource" }, "attemptedTransition": { "type": "string", "description": "Transition that was attempted" }, "attemptedState": { "type": "string", "description": "State the caller asked the resource to move to (federation: POST /federation/v1/state-transitions terminal-conflict 422 carries this alongside `currentState`)." }, "validTransitions": { "type": "array", "items": { "type": "string" }, "description": "Valid transitions from the current state" }, "attemptedAction": { "type": "string", "description": "The /transition action name that was submitted" }, "allowedActions": { "type": "array", "items": { "type": "string" }, "description": "Action names accepted by POST /v1/records/{id}/transition in the current state" }, "refreshUrl": { "type": "string", "description": "Concrete GET URL the agent should re-fetch to read fresh nextActions/validTransitions/allowedActions (set on 422 INVALID_ACTION when the request path includes a record id)." }, "allowedValues": { "type": "array", "items": {}, "description": "Permitted values for the field that failed an enum constraint, or the registered list when the rejection is a \"no such X\" lookup (e.g., unknown type → registered types)." }, "disputeCount": { "type": "integer", "description": "Number of disputes already filed against this record (open + terminal). Surfaced on 422 when the dispute cap is hit." }, "maxDisputes": { "type": "integer", "description": "Maximum disputes allowed on this record (default 1). Surfaced alongside disputeCount when the cap is hit." }, "openDisputeId": { "type": [ "null", "string" ], "format": "uuid", "description": "ID of the currently-open dispute (EVIDENCE_WINDOW or TIER_2_REVIEW). Null when all prior disputes have terminalized. Surfaced on 422 when the dispute cap is hit so the agent can escalate the existing one rather than try to open another." }, "currentStatus": { "type": "string", "description": "Display status of the record at the moment the request was refused. Surfaced on 422 when a dispute is attempted while verification is still in progress." }, "disputeableWhen": { "type": "array", "items": { "type": "string" }, "description": "Display statuses from which POST /v1/records/{recordId}/dispute is accepted. Poll GET /v1/records/{recordId} until status is one of these, then retry." }, "allowedActors": { "type": "array", "items": { "type": "string" }, "description": "Role/actor labels permitted for this action in the current resource state. Surfaced on 403 cross-tier rejections (e.g., parent-principal trying to act on a sub-record it is not direct-principal of)." }, "parentRecordId": { "type": "string", "format": "uuid", "description": "ID of the parent record that rejected the delegation attempt. Surfaced on 422 when the parent state cannot accept children." }, "reason": { "type": "string", "description": "Machine-readable reason code. On 409 conflicts: STATUS_NOT_DISABLED, RECORDS_REFERENCE_TYPE, CONFLICTING_VERSION, RESERVED_PUBLISHER_LABEL, VAULT_SCAN_IN_FLIGHT. On 422 authority-guard refusals: the snake_case guard identifier (has_children_leaf_only, leaf_record, no_children, children_not_terminal, mode_not_auto, mode_not_principal, record_disputed). Branch on this rather than on the prose in `detail`." }, "jobId": { "type": "string", "format": "uuid", "description": "ID of the background job this request is being refused in favour of. Poll GET /v1/admin/vault/scan/{jobId} for its state and result. Present on 409 VAULT_SCAN_IN_FLIGHT." }, "publisher": { "type": "string", "description": "Publisher label on the conflicting schema row." }, "version": { "type": "string", "description": "Manifest version string on the conflicting schema row." }, "incomingDigest": { "type": "string", "description": "sha256: digest of the manifest the caller just submitted." }, "existingDigest": { "type": "string", "description": "sha256: digest of the manifest already registered at this (publisher, type, version)." }, "publishers": { "type": "array", "items": { "type": "string" }, "description": "Candidate publisher labels on a 422 `/problems/ambiguous-publisher`. Emitted by /v1/schemas/{type} reads and writes (pin with `?publisher=`) and by record creation (pin with a `publisher` body field)." }, "pinnedRecords": { "type": "integer", "description": "Records written against the exact registration this delete would remove." }, "unattributableRecords": { "type": "integer", "description": "Records of this type carrying no registration pin, so they block a delete under any publisher label." }, "peerDigest": { "type": "string", "description": "sha256: digest the federation peer claimed in `schemaRef.manifestDigest`." }, "localDigest": { "type": "string", "description": "sha256: digest the receiver holds locally for the same (publisher, type, version, org) tuple." }, "revisionCount": { "type": "integer", "description": "Number of revisions consumed at the moment OVERFLOW_REJECT fired." }, "maxRevisions": { "type": "integer", "description": "Configured maxRevisions cap on the record." }, "terminalReason": { "type": "string", "description": "Machine-readable label naming the system action that terminalized the record (e.g. OVERFLOW_REJECT, ARBITRATION_LOCK, TIME_OUT)." }, "deadline": { "type": "string", "format": "date-time", "description": "The record deadline that had already passed when the request was refused (system TIME_OUT)." }, "previousStatus": { "type": "string", "description": "Display status the record was at immediately before the terminal transition." }, "constraintViolations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Constraint violations for the request" }, "constraint": { "type": "string", "description": "Database constraint that was violated" }, "validationErrors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Schema validation errors" }, "migratedTo": { "type": "string", "description": "Suggested replacement path for a renamed endpoint. Present on 404 responses for routes retired in a migration (e.g. /v1/admin/enterprises → /v1/admin/orgs)." }, "expected": { "type": "string", "description": "Expected JSON type or value, paired with `received` on validation errors." }, "signInputTemplate": { "type": "string", "description": "Exact byte template the Ed25519 proof-of-possession signature must cover, with the domain prefix. Surfaced on the federation 401 for an invalid signature." }, "docs": { "type": "string", "description": "Pointer to the discovery document section describing the failed scheme (e.g. \"/llms.txt (Federation Signing Scheme section)\"). Paired with signInputTemplate + hint on the federation 401." }, "retryAfterSeconds": { "type": "integer", "description": "Seconds to wait before retrying this request. This is temporary — retry the same request after this delay." } }, "additionalProperties": false }, "NextStepAction": { "type": "object", "properties": { "action": { "type": "string", "description": "What to do next" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "description": "HTTP method" }, "href": { "type": "string", "description": "Relative URL template (substitute {id} placeholders)" }, "description": { "type": "string", "description": "Why this step matters" }, "workflowStep": { "type": "integer", "minimum": 1, "description": "1-indexed position of this action in the end-to-end workflow. Only set on the primary forward action of a multi-step flow (not on sibling actions like cancel/view)." }, "workflowTotal": { "type": "integer", "minimum": 1, "description": "Total number of user-visible steps to reach terminal state. Pairs with workflowStep." }, "workflowLabel": { "type": "string", "description": "Human-readable progress label (e.g., \"Step 2 of 3: submit completion\"). Pairs with workflowStep + workflowTotal." }, "afterThis": { "type": "string", "description": "What happens after this action completes. Helps agents plan ahead and avoid stopping at \"work done\" when more steps remain." } }, "additionalProperties": false }, "RecordRow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "performerAgentId": { "type": [ "null", "string" ], "format": "uuid", "description": "Performer agent assigned to fulfill this record. Null when no performer is assigned (notarize-only flow or pre-proposal admin-created records)." }, "principalAgentId": { "type": "string", "format": "uuid", "description": "Named accountable party. Always an agent." }, "createdByKeyId": { "type": "string", "format": "uuid", "description": "API key that created this record. May be admin, agent, or platform — see audit_vault for the full chain of custody." }, "selfPrincipal": { "type": "boolean", "description": "True when principalAgentId equals performerAgentId at creation — the same agent is both principal and performer. Auto-verdict is blocked in this case: the principal must explicitly render verdict." }, "acceptanceStatus": { "type": [ "null", "string" ], "description": "Proposal status: PROPOSED, ACCEPTED, REJECTED, COUNTER_PROPOSED, or BYPASSED. BYPASSED indicates an admin/platform key drove register/activate (or autoActivate) without performer acceptance — the named performer never opted in via /accept. The Signed Statement on that transition carries `acceptanceBypassed: true` + `bypassActorRole` + `bypassReason` for forensic detail." }, "acceptanceRespondedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "When the performer responded to the proposal" }, "parentRecordId": { "type": [ "null", "string" ], "format": "uuid", "description": "Parent record ID in a delegation chain" }, "chainDepth": { "type": "integer", "description": "Depth in delegation chain (0 = top-level)" }, "rootRecordId": { "type": [ "null", "string" ], "format": "uuid", "description": "Root record in the delegation chain" }, "childRecordIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of child records in the delegation chain (present on single-record fetch only)" }, "latestCompletionId": { "type": [ "null", "string" ], "format": "uuid", "description": "Most recent completion id for this record (present on single-record fetch only). Key a verdict to it via POST /v1/records/{id}/verdict without a separate GET /completions round-trip. Null until the first completion is submitted." }, "hasChildren": { "type": "boolean", "description": "True iff this record has at least one delegated child. Maintained by the agledger_records_has_children trigger and reads as live truth (do NOT compute from `childRecordIds.length` — that field is only present on single-record fetches)." }, "parentPrincipalOrgMatchesPerformer": { "type": [ "null", "boolean" ], "description": "Delegation-shell indicator: true when parent record's principal org equals this child's performer org. NULL on root records and on children without an assigned performer. Informational signal — never blocks." }, "commissionPct": { "type": [ "null", "number" ], "description": "Commission percentage for delegation" }, "commissionAmount": { "type": [ "null", "number" ], "description": "Computed commission amount" }, "operatingMode": { "type": "string", "enum": [ "cleartext", "encrypted" ], "description": "Operating mode: cleartext (server-side gate evaluation) or encrypted (server cannot read payloads)" }, "gateMode": { "type": "string", "enum": [ "auto", "principal" ], "description": "Gate mode: auto (rules engine renders the verdict and auto-settles) or principal (engine runs an advisory pass when rules exist, then the principal renders accept/reject)" }, "constraintInheritance": { "type": "string", "enum": [ "none", "advisory", "enforced" ], "description": "Constraint inheritance mode for delegation chains: none (default, no inheritance), advisory (audit warning if child exceeds parent), enforced (block child creation if exceeds parent)" }, "riskClassification": { "type": "string", "enum": [ "unacceptable", "high", "limited", "minimal", "unclassified" ], "description": "EU AI Act risk classification" }, "euAiActDomain": { "type": [ "null", "string" ], "description": "EU AI Act high-risk domain (only when riskClassification=high)" }, "humanOversight": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Human oversight designation per EU AI Act Art. 14" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Arbitrary key-value data for customer use (project refs, tags, integration context)" }, "category": { "type": [ "null", "string" ], "maxLength": 100, "description": "Free-form taxonomy of what kind of artifact this Record represents — denormalized from the Type at create. Immutable. Customer-defined string (e.g. \"decision\", \"delivery-attempt\", \"telemetry-tick\"). No engine semantics." }, "outcome": { "type": [ "null", "string" ], "enum": [ "success", "failure", "denied", "partial", null ], "description": "Optional free-form outcome supplied at create. Stored on metadata.outcome and surfaced here regardless of Type. NOT the gate verdict — that is `verdict` (local gate) or `settlementSignal.outcome` (federation-received records)." }, "correlationId": { "type": [ "null", "string" ], "description": "Optional grouping ID supplied at create. Multiple Records sharing a correlationId can be queried with GET /v1/records/search?correlationId=…" }, "requestedBy": { "type": [ "null", "string" ], "description": "Free-form identifier of the human or upstream system that asked for the work (e.g. \"user:alice@example.com\", \"system:cron-2026-04-25\")." }, "share": { "type": [ "null", "boolean" ], "description": "V1 sharing override. Echoes the value supplied at create — `true`/`false` is an explicit per-record decision; `null` means inherit from the contract type's `defaultShare` then the global `AGLEDGER_DEFAULT_SHARE` (default `true`). The effective value is computed at outbound time, not stored." }, "imported": { "type": "boolean", "description": "True iff the record was inserted via POST /v1/admin/records/import (backfill from a legacy system). False for records created via the live API. Lets dashboards filter \"live activity\" vs \"archival data\" without walking the audit chain. The chain payload also carries this flag on the BACKFILL_IMPORT entry for cryptographic non-repudiation." }, "source": { "type": [ "null", "string" ], "description": "Free-form label provided at backfill time identifying the origin system (e.g. \"legacy-erp\", \"salesforce-export-2024\"). Null on live records. Same value also appears on the BACKFILL_IMPORT chain entry." }, "federationStatus": { "type": [ "null", "string" ], "enum": [ "pending", "delivered", "partial", "failed", "inbound", null ], "description": "Federation rollup for this record. Sender side: `pending` = enqueued but not yet delivered, `delivered` = every (peer, kind) row reached 2xx, `partial` = some delivered, some pending or failed, `failed` = every row terminally failed (DLQ). Receiver side: `inbound` = this Server RECEIVED the record's federation traffic from a peer — read `settlementSignal` (source `inbound`, `receivedFrom` names the peer) for the originator's verdict and reason; there is no sender-side delivery rollup to report. `null` when the record never federated (no active peers, share=false, or no rows yet). For per-peer breakdown see `sharedToPeers` and `settlementSignal.{deliveredToPeers,pendingToPeers,failedToPeers}`." }, "sharedToPeers": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Distinct peer hub_ids the record was dispatched to. Empty when the record did not federate (share=false or no active peers)." }, "coSignRequired": { "type": [ "null", "boolean" ], "description": "V1 Additive E — schema-level bilateral co-sign opt-in for this contract type, so an LLM agent can see the contract type's posture before any signal fires. **Populated on single-record fetch (GET /v1/records/{id}) only**; list/search/batch responses omit it (left `null`) — on those, read `coSignStatus` (which IS hydrated: `not_required` vs `pending`/`succeeded`/`failed` distinguishes co-sign types) or GET /v1/schemas/{type}. `null` for notarize-only types or when the schema is unresolved (federated record with unknown schemaRef)." }, "coSignStatus": { "type": [ "null", "string" ], "enum": [ "not_required", "pending", "succeeded", "failed", null ], "description": "Bilateral co-sign rollup. `not_required` for single-sig contracts; `pending` while a co-sign request is in flight; `succeeded` once a counter-signature was returned; `failed` on terminal co-sign failure (peer mismatch, exhausted retries — the parent signal row also goes to `failed`). `null` when no signal has fired yet." }, "counterSignature": { "type": [ "null", "string" ], "description": "Hex Ed25519 counter-signature attached to the most recent successful co-sign. Verifiable offline against the peer's published vault keys (`GET /.well-known/agledger-vault-keys.json` on the peer Server). Null when co-sign is not configured or has not yet succeeded." }, "settlementSignal": { "type": [ "null", "object" ], "additionalProperties": false, "required": [ "recommendation", "outcome", "deliveredToPeers", "pendingToPeers", "failedToPeers", "idempotencyKey" ], "properties": { "recommendation": { "type": "string", "enum": [ "SETTLE", "HOLD", "RELEASE" ] }, "outcome": { "type": [ "null", "string" ], "enum": [ "accept", "reject", null ], "description": "Verdict the recommendation binds to — `accept` (recommendation typically SETTLE) or `reject` (HOLD). Mirrors the value engines and federation projections write to the wire; pre-diff this enum read [PASS, FAIL] which never matched the runtime values that ship today." }, "reasonCode": { "type": [ "null", "string" ], "description": "Machine-readable label naming the cause behind this signal so a payment platform can branch on `recommendation: HOLD` (gate failure vs timeout vs cancel vs dispute-overturn) AND on `recommendation: SETTLE` (auto-mode engine pass vs principal-mode human accept). Engine-emitted values (verdict path): `AUTO_SETTLE` / `AUTO_FAIL` (auto-mode), `AUTO_SETTLE_WITHIN_TOLERANCE` (auto-mode SETTLE where a numeric/datetime rule cleared only via its non-zero `tolerance` band, not the base criteria threshold — the band-widened clear is on-chain in `verdictChecks`; this label surfaces it in the terminal so an auditor/platform can tell it from a clean within-threshold settle), `PRINCIPAL_ACCEPT` / `PRINCIPAL_REJECT` (principal-mode), `DISPUTE_OVERTURNED` (RELEASE from a dispute overturn). Read-path local-synthesis additionally mirrors the record's `terminalReason` for system-driven terminals (`TIMED_OUT`, `REMEDIATED`, `CANCEL_PRE_WORK`, `CANCEL_IN_PROGRESS`, `OVERFLOW_REJECT`, `ARBITRATION_LOCK`) and adds `VERDICT_REJECTED` as a legacy catch-all for the recoverable-FAILED display state. Null when the cause isn't classifiable (e.g., bare REJECTED without a known prefix) or on projections predating the fix." }, "failingRuleIds": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "RuleIds that failed when the engine ran a gate evaluation that produced this signal. Populated only when rules ran AND at least one failed (HOLD recommendation, gated record). Null for non-rule failures (TIMED_OUT, cancel, dispute-overturn, AUTO_SETTLE) and on projections predating the fix. The structured per-rule check details (expected/actual/tolerance) stay on the record's `verdictChecks` field — this is just the discriminator for routing." }, "reason": { "type": [ "null", "string" ], "description": "Free-text human-readable hint. Mirrors `record.lastVerdictReason` (engine summary for auto-gate) or the principal's verdict notes (principal-mode). Optional supplement to `reasonCode` + `failingRuleIds`. Null on projections predating the fix." }, "deliveredToPeers": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "pendingToPeers": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "failedToPeers": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "idempotencyKey": { "type": [ "null", "string" ], "format": "uuid" }, "coSignStatus": { "type": [ "null", "string" ], "enum": [ "not_required", "pending", "succeeded", "failed", null ], "description": "Bilateral co-sign rollup surfaced ON the signal a payment platform reads — not only at the record top level. `succeeded` (with `counterSignature` set) is the visible proof this SETTLE/HOLD was dual-signed by the receiving peer; `not_required` for single-sig contract types; `pending` while a co-sign request is in flight; `failed` on terminal co-sign failure. Null when no signal row carries co-sign metadata yet. Present only on `source: \"outbound\"` (the firing Server holds the counter-signature); `inbound`/`local` omit it." }, "counterSignature": { "type": [ "null", "string" ], "description": "Hex Ed25519 counter-signature from the most recent successful co-sign, attached to this Settlement Signal. Verifiable offline against the peer's published vault keys (`GET /.well-known/agledger-vault-keys.json` on the peer Server). Mirrors the record top-level `counterSignature` so a consumer reading `settlementSignal` sees the bilateral proof inline. Null when co-sign is not configured or has not yet succeeded; present only on `source: \"outbound\"`." }, "validUntil": { "type": [ "null", "string" ], "format": "date-time", "description": "Expiry of this Settlement Signal — a payment integration should reject a HOLD/RELEASE whose `validUntil` is in the past as stale. Present on both outbound and inbound; null on projections predating the fix." }, "outcomeHash": { "type": [ "null", "string" ], "description": "Hash binding this settle/hold decision to the underlying verdict outcome, for audit. The same value rides the `federation.settlement.signal` event and the bilateral co-sign wire. Null on projections predating the fix." }, "source": { "type": "string", "enum": [ "outbound", "inbound", "local" ], "description": "`outbound` — this Server emitted the signal; per-peer arrays describe fanout (may be empty when the fanout has not yet been attempted). `inbound` — this Server received the signal from a federation peer (per-peer arrays are empty; see `receivedFrom`). `local` — verdict-derived synthesis when the federation projection has not (yet) landed: either the race window right after submitVerdict (publisher fires post-commit, GET lands before the projection INSERT) or a non-federated install (no peers configured). `local` carries empty pending/delivered/failed arrays and null idempotencyKey/validUntil/outcomeHash — consumers can wait + re-read for the federation projection to overtake it, or treat it as the final signal on standalone installs. Omitted on legacy outbound projections." }, "receivedFrom": { "type": [ "null", "object" ], "description": "Present only when `source: \"inbound\"` — names the originating peer.", "required": [ "peerHubId", "receivedAt" ], "properties": { "peerHubId": { "type": "string", "format": "uuid" }, "receivedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "description": "Most recent Settlement Signal on this record. `null` when no signal has fired. Two shapes share this field, discriminated by `source`: `outbound` (this Server emitted the signal) carries per-peer fanout arrays; `inbound` (this Server received the signal from a federation peer) carries `receivedFrom` and empty per-peer arrays. Customers at a receiver Server should look here — not `/v1/events` — to confirm a record was settled." }, "type": { "type": "string" }, "contractVersion": { "type": "string" }, "publisher": { "type": [ "null", "string" ], "description": "Publisher label of the registration this record binds to. Together with `type` and `contractVersion` it names exactly which schema the record was judged against, which `type` alone cannot when two publishers offer the same `record_type` in this org. Records created through this API carry it whether or not you pinned it on create, so a single-publisher org gets its one label (usually `local`) rather than null. Records backfilled through `POST /v1/admin/records/import` carry it too: the import validates each item against a registration in this org and pins the record to it, so an imported record names the schema it was judged against, and an ambiguous bare `type` is refused there with the same 422 as on create. `null` means the record has no such binding, which is the case for records the engine never validated against a local registration: federation-received records, where this Server did not run the gate and the originator did, against its own registration. Treat `null` as \"ask the originator\", not as \"the schema is missing locally\"." }, "schemaUrl": { "type": [ "null", "string" ], "description": "URL to the type schema for discovering expected criteria and evidence structure. Carries `?publisher=` whenever the publisher is known, so the link resolves even for a type two publishers offer (e.g. /v1/schemas/notarize-generic-v1?publisher=local). `null` on a federation-received record whose type this Server does not hold: the record was judged against the originator's registration, and no URL here would resolve to it. A link into this Server's own namespace would either 404 on a type that does exist elsewhere, or answer 200 with this Server's unrelated schema of the same name, so the field is null instead and the record's `nextSteps` carry the originating peer's manifest URL and the `/v1/schemas/import` call that mirrors it. Once mirrored (same publisher label, same manifest, therefore the same `manifestDigest`) this becomes a scoped URL that resolves." }, "platform": { "type": "string" }, "platformRef": { "type": [ "null", "string" ] }, "projectRef": { "type": [ "null", "string" ], "description": "External project reference for grouping records" }, "externalTaskId": { "type": [ "null", "string" ], "description": "External task system ID for linking records to CI/CD pipelines, RPA tasks, or workflow engines" }, "enforcementOverrides": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Per-record enforcement overrides (Phase 3). Can only relax org settings." }, "dependsOn": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Informational dependency references to other record IDs (no activation gating)" }, "status": { "type": "string", "enum": [ "CREATED", "PROPOSED", "ACTIVE", "PROCESSING", "REVISION_REQUESTED", "DISPUTED", "FULFILLED", "FAILED", "REMEDIATED", "EXPIRED", "PENDING_ARBITRATION", "CANCELLED", "REJECTED", "RECORDED" ], "description": "Customer-facing display lifecycle state — 14 business-meaningful values that map from a wider set of internal state-machine states. The same display token can correspond to multiple internal states (e.g. CREATED covers internal DRAFT and REGISTERED; PROCESSING covers COMPLETION_ACCEPTED and PENDING_VERDICT; CANCELLED covers CANCELLED_PRE_WORK and CANCELLED_IN_PROGRESS; EXPIRED is the alias for internal TIMED_OUT). Match against THIS enum, not internal-state names. Display tokens: CREATED (not yet active), PROPOSED (agent proposal pending), ACTIVE (awaiting work — covers COMPLETION_INVALID retries), PROCESSING (completion/gate evaluation in progress), REVISION_REQUESTED, DISPUTED (tribunal review), FULFILLED, FAILED, REMEDIATED, EXPIRED (deadline missed — internal TIMED_OUT), PENDING_ARBITRATION (tribunal exhausted), CANCELLED, REJECTED, RECORDED (terminal: notarize-only Type — Records that did not declare a completion phase land here at create)." }, "criteria": { "type": "object", "additionalProperties": true, "description": "Acceptance criteria matching the type JSON Schema" }, "tolerance": { "type": "object", "additionalProperties": true, "description": "Per-record tolerance values. Most keys are gate-evaluation bands (e.g. quantity deviation %). graceSeconds is the exception: a deadline grace window (effective expiry = deadline + graceSeconds)." }, "deadline": { "type": [ "null", "string" ], "format": "date-time", "description": "ISO 8601 deadline after which the record auto-expires" }, "verdict": { "type": [ "null", "string" ], "enum": [ "accept", "reject", null ], "description": "Phase 2 gate verdict (null until the gate evaluation completes). Check verdictChecks for per-rule details. Stays null on federation-received records (federationStatus `inbound`) — this Server never ran the gate; the originator's verdict surfaces on `settlementSignal.outcome` with `settlementSignal.reason`." }, "verdictChecks": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Detailed per-rule gate-evaluation results with tolerance bands (e.g., quantity_match, price_ceiling). Each rule includes pass/fail, expected vs actual values, and tolerance info." }, "lastTransitionReason": { "type": [ "null", "string" ], "description": "Reason provided for the most recent state transition" }, "terminalReason": { "type": [ "null", "string" ], "description": "Machine-readable label naming the system action that terminalized this record (OVERFLOW_REJECT, TIMED_OUT, ARBITRATION_LOCK, AUTO_SETTLE, AUTO_SETTLE_WITHIN_TOLERANCE, PRINCIPAL_ACCEPT, CANCEL_PRE_WORK, CANCEL_IN_PROGRESS, REMEDIATED, RECORDED). A FULFILLED record gated in principal mode reads `PRINCIPAL_ACCEPT` (a human/principal rendered the verdict), distinct from auto-mode `AUTO_SETTLE` — so a reconciliation system can tell principal-approved from auto-approved terminals. An auto-mode FULFILLED whose gate cleared only because a non-zero `tolerance` band widened a numeric/datetime rule past the base criteria threshold reads `AUTO_SETTLE_WITHIN_TOLERANCE` instead of `AUTO_SETTLE`, so a tolerance-widened clear is distinguishable from a clean within-threshold one (the tolerance value itself is on-chain in `verdictChecks` / the audit export). Both reject-side terminals — auto-mode `AUTO_FAIL` and principal-mode `PRINCIPAL_REJECT` — land in VERDICT_REJECTED, a non-terminal/recoverable state (overturn → FULFILLED, remediate, revise, and dispute all remain open), so `terminalReason` is null there by design; read `settlementSignal.reasonCode` (`AUTO_FAIL` in auto mode, `PRINCIPAL_REJECT` in principal mode) for the reject cause. This is deliberately asymmetric with the accept side: a passing gate lands at the true terminal FULFILLED and carries its cause here, while a failing gate stays recoverable and carries its cause on the signal. Null when the record is non-terminal or when an unknown writer landed it in a terminal state. Mirrors the same value the 422 envelope on OVERFLOW_REJECT carries in `context.terminalReason`." }, "lastTransitionBy": { "type": [ "null", "string" ], "description": "Identifier of who triggered the most recent state transition" }, "lastVerdictReason": { "type": [ "null", "string" ], "description": "Reason from the most recent verdict or revision request. Unlike lastTransitionReason, this persists across subsequent state changes so performers can always see why their completion was rejected. Stays null on federation-received records (federationStatus `inbound`) — the originator's verdict reason surfaces on `settlementSignal.reason` / `settlementSignal.reasonCode`." }, "lastVerdictAt": { "type": [ "null", "string" ], "format": "date-time", "description": "When the most recent verdict or revision request was made. Stays null on federation-received records — see `settlementSignal.receivedFrom.receivedAt` for when the originator's signal arrived." }, "submissionCount": { "type": "integer", "description": "Number of completions submitted (incremented on each accepted completion)" }, "maxSubmissions": { "type": [ "null", "integer" ], "description": "Maximum allowed completion submissions (null = unlimited)" }, "revisionCount": { "type": "integer", "description": "Number of revisions consumed by RESUBMIT_COMPLETION calls. Capped by `maxRevisions`: when this equals it, the next resubmit terminates the record at REJECTED via OVERFLOW_REJECT. Read this before requesting another revision." }, "maxRevisions": { "type": "integer", "description": "Maximum revisions allowed before OVERFLOW_REJECT (default 3). Compare with revisionCount to know remaining capacity." }, "disputeCount": { "type": "integer", "description": "Number of disputes opened against this record. Capped by `maxDisputes`: when this equals it, no further DISPUTE actions are accepted. Default cap is 1 in v1." }, "maxDisputes": { "type": "integer", "description": "Maximum disputes allowed (default 1). Compare with disputeCount to know whether opening another DISPUTE will be accepted." }, "pastDeadline": { "type": "boolean", "description": "True iff a deadline is set AND has passed. When true, the engine's in-tx submit guard rejects any /completions call (terminalizes at TIMED_OUT). Read this before submitting — saves a round-trip on past-deadline records and lets the agent fall through to /cancel cleanly." }, "awaitingActor": { "type": [ "null", "string" ], "enum": [ "principal", "performer", "system", "arbitration", null ], "description": "Who the record is waiting on for forward progress. Disambiguates display `PROCESSING` (engine vs principal) and surfaces the wait state without forcing a `gate-status` round-trip + 403-probe. `principal` = awaiting a principal-side action: accept/reject verdict (PENDING_VERDICT / DISPUTED), or a pre-work move only the principal can make — display `CREATED` awaiting propose/activate, including the wait after a performer accepts. `performer` = assigned to a performer who hasn't acted yet (PROPOSED, ACTIVE-with-performer, REVISION_REQUESTED). `system` = engine mid-evaluation (COMPLETION_ACCEPTED — gate worker about to run). `arbitration` = tier-3 tribunal review (PENDING_ARBITRATION). `null` = no actor is blocking (terminal states; ACTIVE with no performer)." }, "version": { "type": "integer", "description": "Optimistic concurrency version number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "activatedAt": { "type": [ "null", "string" ], "format": "date-time" }, "fulfilledAt": { "type": [ "null", "string" ], "format": "date-time" }, "expiredAt": { "type": [ "null", "string" ], "format": "date-time", "description": "When the expiry worker transitioned this record to EXPIRED. Null until the deadline passes and the sweep fires." }, "disputeId": { "type": [ "null", "string" ], "format": "uuid", "description": "ID of the most recent dispute against this record (open or resolved). Null if no dispute has ever been filed. Present only on single-record fetch (`GET /v1/records/{id}`); list endpoints omit it. Use `GET /v1/records/{id}/dispute` for the full dispute object + evidence history." }, "disputeStatus": { "type": [ "null", "string" ], "enum": [ "EVIDENCE_WINDOW", "TIER_2_REVIEW", "ESCALATED", "TIER_3_ARBITRATION", "RESOLVED", "WITHDRAWN", null ], "description": "Status of the most recent dispute. Null if no dispute exists. Now hydrated on list endpoints too (previously single-record-only — N+1 fetch from a compliance dashboard). Matches the externally-observable subset of dispute statuses (engine never commits transient `OPENED`/`TIER_1_REVIEW`)." }, "hasDispute": { "type": "boolean", "description": "Derived from `disputeCount > 0` so dashboards can render a quick \"disputed yes/no\" badge without inspecting the count. Populated on both per-record and list responses." }, "completionHint": { "type": [ "null", "object" ], "properties": { "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required field names for completion evidence submission" }, "optionalFields": { "type": "array", "items": { "type": "string" }, "description": "Optional field names accepted by the completion schema (non-required properties)" }, "schemaUrl": { "type": "string", "description": "URL to the full completion schema" } }, "additionalProperties": false, "description": "Lightweight hint showing required and optional completion evidence fields. Use schemaUrl for the full JSON Schema with types and descriptions. Populated on create-record responses so the agent does not have to round-trip /v1/schemas/{type} before submitting a completion." }, "nextActions": { "type": "array", "items": { "type": "string", "enum": [ "register", "propose", "activate", "cancel" ] }, "description": "Exact action names that `POST /v1/records/{id}/transition` accepts right now. Empty when no transition applies (e.g., terminal states or awaiting-completion states). Actions on other endpoints (submit completion, counter-propose, reject, request-revision, verdict) are surfaced via `nextSteps` with method+path." }, "validTransitions": { "type": "array", "items": { "type": "string", "enum": [ "CREATED", "PROPOSED", "ACTIVE", "PROCESSING", "REVISION_REQUESTED", "DISPUTED", "FULFILLED", "FAILED", "REMEDIATED", "EXPIRED", "PENDING_ARBITRATION", "CANCELLED", "REJECTED", "RECORDED" ] }, "description": "Display states (matching the same enum as `status` above) the record can transition to next. These are CUSTOMER-FACING display tokens — internal state-machine names (DRAFT/REGISTERED/COMPLETION_ACCEPTED/PENDING_VERDICT/TIMED_OUT/etc.) are mapped to display tokens before emission. Match against this enum, not internal-state names. For action verbs accepted by `POST /v1/records/{id}/transition`, read `nextActions`; for full hyperlinks (including non-/transition endpoints like /completions, /dispute, /outcome), read `nextSteps`." }, "advisoryWarnings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "description": "Advisory enforcement warnings (only present when org advisory mode is enabled and a constraint was exceeded but allowed)" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" }, "description": "External entity references attached to this record (present on single-record fetch only)" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls based on current record state. Guides AI agents through the record lifecycle without requiring prior knowledge of the state machine." }, "recordRead": { "type": "object", "properties": { "leafIndex": { "type": "integer", "minimum": 0, "description": "Per-org monotonic leaf index in the org_admin_reads chain." }, "leafHash": { "type": "string", "minLength": 64, "maxLength": 64, "description": "Hex sha256 of the canonical chain entry — the leaf hash a Merkle inclusion proof verifies against the checkpoint root." }, "signedCheckpointRef": { "type": [ "null", "string" ], "format": "uuid", "description": "Most recent signed checkpoint that includes this leaf, or null until the next 6h sweep covers it." } }, "required": [ "leafIndex", "leafHash", "signedCheckpointRef" ], "additionalProperties": false, "description": "SCITT-style inclusion-proof completion. Present only on org-admin cross-party reads — proves the read was logged." }, "signedStatement": { "type": "object", "properties": { "chainPosition": { "type": "integer", "minimum": 1, "description": "Per-record monotonic chain position of the head Signed Statement (1-indexed)." }, "leafHash": { "type": "string", "minLength": 64, "maxLength": 64, "description": "Hex sha256 over the canonical COSE_Sign1 envelope bytes." }, "previousHash": { "type": [ "null", "string" ], "minLength": 64, "maxLength": 64, "description": "leafHash of the prior entry (null only on chain_position=1)." }, "signingKeyId": { "type": [ "null", "string" ], "description": "ID of the vault signing key — resolves to a public key at GET /v1/verification-keys." }, "signedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Signed instant of the head Signed Statement — the CWT `iat` claim (second precision) sealed in the COSE_Sign1 protected header. THE authoritative timestamp for time-anchored contracts (wait windows, notice clocks); the record's `createdAt` is a millisecond-precision DB clock that only approximates it. Null if the envelope fails to decode." }, "signedCheckpointRef": { "type": [ "null", "string" ], "format": "uuid", "description": "Most recent signed checkpoint covering this chain position, or null until the next 6h sweep." }, "url": { "type": "string", "description": "Path to the canonical COSE_Sign1 envelope for this record's head Signed Statement (application/cose)." } }, "required": [ "chainPosition", "leafHash", "previousHash", "signingKeyId", "signedAt", "signedCheckpointRef", "url" ], "additionalProperties": false, "description": "Inline tamper-evident pointer to the head Signed Statement (COSE_Sign1) in this record's audit chain. Lets a notarize-only caller verify the record was chained without a follow-up call to /v1/records/{id}/audit-export. The `url` resolves to the canonical COSE_Sign1 envelope." }, "integrity": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "True iff (a) the record's full audit chain re-verifies — per-entry hash re-derive from the COSE_Sign1 envelope, hash linkage, signatures, checkpoint cross-check — AND (b) the record fields in THIS response match what the chain asserts (type, orgId, principalAgentId, parentRecordId, criteria). False means this response body may not match the signed evidence — treat GET /v1/records/{id}/audit-export as the authoritative source." }, "integrityLevel": { "type": "string", "enum": [ "hash_chain_only", "hash_chain_partial_signatures", "hash_chain_and_signatures", "invalid" ], "description": "Strength of the chain verification: whether every chain entry was independently signed, or only hash-linked." }, "reason": { "type": [ "null", "string" ], "description": "Failure class when verified=false. `record_projection_drift` = the record row served here diverges from the verified chain (out-of-band database edit of the records table — see driftFields). Chain-level classes: chain_broken_at, payload_drift, checkpoint_hash_mismatch, audit_vault_row_missing_for_checkpoint, oidc_actor_drift, cert_*, signature_invalid, signing_key_unknown, unsupported_algorithm. Null when verified." }, "entries": { "type": "integer", "minimum": 0, "description": "Number of audit-chain entries verified." }, "projectionChecked": { "type": "boolean", "description": "True when the row-vs-chain comparison ran. False for records whose chain has no creation assertion (imported/backfilled, federation-projected) — for those, only the chain itself was verified, not this response body against it." }, "driftFields": { "type": "array", "items": { "type": "string" }, "description": "Record fields whose served value diverges from the chain-asserted value. Empty when clean. Non-empty is evidence of direct database modification of the records row." } }, "required": [ "verified", "integrityLevel", "reason", "entries", "projectionChecked", "driftFields" ], "additionalProperties": false, "description": "On-read chain verification result. Present only when requested via `?integrity=true` on GET /v1/records/{id} (full-chain cryptographic verify per call — expensive, so opt-in). The record fields in this response are a denormalized projection of the signed audit chain; the chain in audit_vault is the evidence. Absent ≠ verified." } }, "additionalProperties": false }, "Completion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Task attestation evidence payload" }, "evidenceHash": { "type": "string", "description": "SHA-256 hash of the canonicalized evidence payload" }, "structuralValidation": { "type": "string", "enum": [ "ACCEPTED", "INVALID", "WARNING" ], "description": "Phase 1 structural validation result. ACCEPTED = evidence conforms to schema. WARNING = evidence has issues but accepted (advisory mode). INVALID = schema mismatch (rejected)." }, "validationErrors": { "type": [ "null", "array" ], "items": { "type": "object", "additionalProperties": true }, "description": "JSON Schema validation errors (present when structuralValidation is INVALID)" }, "warnings": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "message": { "type": "string" }, "instancePath": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "description": "Schema validation warnings (present when structuralValidation is WARNING — advisory mode). These are the errors that would have caused rejection under enforced mode." }, "idempotencyKey": { "type": [ "null", "string" ], "description": "Client-provided idempotency key for deduplication" }, "recordStatus": { "type": "string", "description": "Current record status after this completion was processed" }, "verdict": { "type": [ "null", "string" ], "enum": [ "PASS", "FAIL", null ], "description": "Phase 2 gate evaluation outcome when the gate ran inline (auto mode + non-encrypted). Null when the gate was skipped (encrypted records, principal-mode) or deferred to the worker. Lets the caller learn the verdict in one round-trip without a follow-up GET on the record." }, "lastVerdictReason": { "type": [ "null", "string" ], "description": "Human-readable verdict text — same string surfaced on GET /v1/records/{id}.lastVerdictReason. Populated whenever verdict is populated." }, "settlementSignal": { "type": [ "null", "object" ], "properties": { "recommendation": { "type": "string", "enum": [ "SETTLE", "HOLD", "RELEASE" ], "description": "The gate decision in GET /v1/records vocabulary: SETTLE (record settled FULFILLED), HOLD (held — e.g. failed a rule), RELEASE (dispute overturn)." }, "outcome": { "type": "string", "enum": [ "accept", "reject" ], "description": "Engine verdict that drove the recommendation." }, "reasonCode": { "type": [ "null", "string" ], "description": "Discriminator code (same as the settlement webhook), e.g. AUTO_SETTLE — or AUTO_SETTLE_WITHIN_TOLERANCE when the gate cleared only via a non-zero tolerance band rather than the base criteria threshold." } }, "additionalProperties": false, "description": "The auto-gate's settlement decision, surfaced inline so the caller learns settle-vs-hold-vs-reject at completion time without a follow-up GET. `structuralValidation:\"ACCEPTED\"` means only the body parsed — THIS field carries the gate's decision. Null when the gate did not render inline (encrypted records, principal-mode held at PENDING_VERDICT, or inline run skipped) — read `recordStatus` and GET /v1/records/{id} in that case." }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls after completion submission (e.g., check gate status)" } }, "additionalProperties": false }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "description": "HTTPS endpoint that receives webhook deliveries" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "Event type filter. `[\"*\"]` means all events are delivered (canonical wildcard sentinel — equivalent to omitting the field on create). Any other array restricts to the listed types only." }, "recordTypes": { "type": "array", "items": { "type": "string" }, "description": "Record-type filter for record-scoped events. `[\"*\"]` means all record types (wildcard sentinel). Any other array means record events are delivered ONLY for the listed types (fail-closed)." }, "isActive": { "type": "boolean", "description": "Whether the subscription is active (auto-disabled on 410 response)" }, "isPaused": { "type": "boolean", "description": "Whether deliveries are temporarily paused (subscription remains active)" }, "format": { "type": "string", "enum": [ "standard", "cloudevents" ], "description": "Payload format: standard (default) or CloudEvents 1.0 envelope" }, "signingAlg": { "type": "string", "enum": [ "hmac", "ed25519", "ecdsa-p256-sha256" ], "description": "Delivery signing scheme. `hmac` (shared secret, default), or an RFC 9421 registered name matching the active vault key's algorithm (`ed25519` by default; `ecdsa-p256-sha256` on a Server opted into ES256): RFC 9421 HTTP Message Signatures signed with the Server vault key, verifiable against /v1/verification-keys with no shared secret (non-repudiation)." }, "createdAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "HMAC-SHA256 signing secret (returned ONCE on creation/rotation of an `hmac` subscription -- store it securely). Absent for asymmetric (`ed25519`/`ecdsa-p256-sha256`) subscriptions, which sign with the vault key." }, "secretGraceActive": { "type": "boolean", "description": "True when a previous secret is still valid within the grace period after rotation" }, "secretGraceExpiresAt": { "type": [ "null", "string" ], "format": "date-time", "description": "When the rotation grace period expires (previous secret becomes invalid)" }, "circuitState": { "type": "string", "enum": [ "closed", "open", "half_open" ], "description": "Circuit breaker state: closed (healthy), open (failing, deliveries skipped), half_open (probing with one delivery)" }, "consecutiveFailures": { "type": "integer", "description": "Number of consecutive delivery failures since last success" }, "lastSuccessfulAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Timestamp of last successful delivery" }, "lastFailureAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Timestamp of last failed delivery — pair with consecutiveFailures and circuitState for \"how long has this endpoint been down\" dashboards" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls (present on creation and rotation responses)" } }, "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "Event type that triggered this delivery" }, "status": { "type": "string", "description": "Delivery status: PENDING, DELIVERED, FAILED, DEAD_LETTER" }, "attemptNumber": { "type": "integer", "description": "Current retry attempt (1-based)" }, "responseStatus": { "type": [ "null", "integer" ], "description": "HTTP status code from the consumer" }, "responseBody": { "type": [ "null", "string" ], "description": "Response body from the consumer (truncated)" }, "signature": { "type": [ "null", "string" ], "description": "Signature sent with the delivery — the `X-AGLedger-Signature` header value for hmac subs, or the RFC 9421 `Signature` header value for ed25519 subs" }, "requestBody": { "type": [ "null", "string" ], "description": "Raw JSON body sent to the endpoint — the exact bytes covered by the signature (HMAC input for hmac, Content-Digest for ed25519)" }, "nextRetryAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Scheduled time for next retry attempt" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Timestamp when delivery was confirmed" } }, "additionalProperties": false }, "DisputeResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "initiatedByRole": { "type": "string", "enum": [ "principal", "performer", "org-admin", "platform" ], "description": "Structural role of the dispute initiator relative to the record. `principal` and `performer` are the two parties to the disputed record; `org-admin` is a org-admin key acting on either side; `platform` is reserved for cross-org intervention." }, "initiatedById": { "type": "string", "format": "uuid", "description": "For agent keys (`principal`/`performer`), this is the agent UUID. For org-admin keys, this is the org UUID." }, "grounds": { "type": "string", "description": "Dispute grounds category" }, "context": { "type": [ "null", "string" ], "description": "Free-text context explaining the dispute" }, "status": { "type": "string", "enum": [ "EVIDENCE_WINDOW", "TIER_2_REVIEW", "ESCALATED", "TIER_3_ARBITRATION", "RESOLVED", "WITHDRAWN" ], "description": "Dispute lifecycle state. Externally-observable values only — the engine writes transient `OPENED`/`TIER_1_REVIEW` inside the same transaction that opens the dispute and never commits a row at those states. Match against this enum." }, "currentTier": { "type": "integer", "description": "Current dispute tier (1 = auto, 2 = manual review, 3 = binding arbitration)" }, "outcome": { "type": [ "null", "string" ], "description": "Resolution outcome: UPHELD, OVERTURNED, or SPLIT" }, "resolutionRationale": { "type": [ "null", "string" ], "description": "Explanation of the resolution decision" }, "feeChargedTo": { "type": [ "null", "string" ], "description": "Party charged the arbitration fee. **Engine does NOT compute fees** — AGLedger is the record-keeper, not the arbiter. Stays `null` until an external tribunal/admin process records the verdict. Tribunal integrations write this via the dispute repository on resolution." }, "feeAmount": { "type": [ "null", "string" ], "description": "Arbitration fee amount. **Engine does NOT compute fees** (record-keeper, not arbiter). Stays `null` until an external tribunal records the verdict." }, "feeCurrency": { "type": [ "null", "string" ], "description": "Currency of the arbitration fee (e.g., USD, EUR). Set by the external tribunal alongside `feeAmount`." }, "evidenceWindowClosesAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Deadline for evidence submission" }, "createdAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "null", "string" ], "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls for the dispute workflow" } }, "additionalProperties": false }, "DisputeEvidence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "disputeId": { "type": "string", "format": "uuid" }, "submittedByRole": { "type": "string" }, "submittedById": { "type": "string", "format": "uuid" }, "evidenceType": { "type": "string", "description": "Type of evidence: screenshot, external_lookup, document, communication, or other" }, "payload": { "type": "object", "additionalProperties": true, "description": "Evidence data payload" }, "payloadHash": { "type": "string", "description": "SHA-256 hash of the canonicalized evidence payload" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ReputationScore": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "Type this score applies to" }, "reliabilityScore": { "type": [ "null", "number" ], "description": "Task completion reliability (0-1)" }, "accuracyScore": { "type": [ "null", "number" ], "description": "Evidence accuracy vs record criteria, adjusted for overturned verdicts (0-1)" }, "efficiencyScore": { "type": [ "null", "number" ], "description": "Efficiency (0-1). v1 placeholder: currently mirrors accuracy until activation→completion timing is tracked." }, "compositeScore": { "type": [ "null", "number" ], "description": "Weighted composite of all dimensions (0-1)" }, "confidenceLevel": { "type": [ "null", "number" ], "description": "Statistical confidence (0-1); tightens as transaction volume grows" }, "lifetimeRecords": { "type": "integer", "description": "Records ever assigned to this agent for this type (monotonic)" }, "lifetimeVerdicts": { "type": "integer", "description": "Gate verdicts ever rendered for this agent+contract (monotonic)" }, "lifetimeAccepted": { "type": "integer", "description": "Verdicts accepted, ever (monotonic — includes verdicts later overturned)" }, "lifetimeCompletions": { "type": "integer", "description": "Completions ever accepted from this agent for this type (monotonic)" }, "reversals": { "type": "integer", "description": "Count of dispute OVERTURNED outcomes; accuracy subtracts these from lifetimeAccepted" }, "lastUpdatedAt": { "type": "string", "format": "date-time" }, "formulaVersion": { "type": "integer", "description": "Scoring formula version for reproducibility" } }, "additionalProperties": false }, "EntityReference": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "system": { "type": "string" }, "refType": { "type": "string" }, "refId": { "type": "string" }, "displayName": { "type": [ "null", "string" ] }, "uri": { "type": [ "null", "string" ] }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string" } }, "additionalProperties": false } } }, "paths": { "/metrics": { "get": { "operationId": "getMetrics", "summary": "Prometheus metrics", "tags": [ "Observability" ], "description": "Returns Prometheus-format metrics. Authentication options: (a) METRICS_AUTH_TOKEN — bearer-token gate, no API-key auth required; (b) restrict at the network layer (private ingress, VPC, LB rule). Default is public (matches prior behavior). Production installs MUST enable one of these or expose /metrics on a worker-only port.", "security": [], "responses": { "200": { "description": "Prometheus metrics in text format.", "content": { "text/plain; version=0.0.4; charset=utf-8": { "schema": { "description": "Prometheus metrics in text format.", "type": "string" } } } }, "401": { "description": "Bearer token missing or invalid (only returned when METRICS_AUTH_TOKEN is set).", "content": { "application/problem+json": { "schema": { "description": "Bearer token missing or invalid (only returned when METRICS_AUTH_TOKEN is set).", "type": "string" } } } } } } }, "/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "tags": [ "Health" ], "description": "Returns service health status. No authentication or rate limiting. Use this endpoint for load balancer health checks and connectivity verification. Aliased at /healthz for Kubernetes-canonical clients.", "security": [], "responses": { "200": { "description": "Service is healthy.", "content": { "application/json": { "schema": { "description": "Service is healthy.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string", "description": "AGLedger API version" }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } } } } }, "/healthz": { "get": { "operationId": "healthCheckKubernetes", "summary": "Health check (Kubernetes-canonical alias for /health)", "tags": [ "Health" ], "description": "Behaves identically to /health. Present for clients that follow the /healthz, /readyz, /livez convention.", "security": [], "responses": { "200": { "description": "Service is healthy.", "content": { "application/json": { "schema": { "description": "Service is healthy.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string", "description": "AGLedger API version" }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } } } } }, "/health/ready": { "get": { "operationId": "readinessCheck", "summary": "Readiness check", "tags": [ "Health" ], "description": "Verifies the service can serve requests by probing database connectivity. Returns 200 when ready, 503 when dependencies are unavailable. Use this for Kubernetes readiness probes and Docker Compose healthchecks. Use /health for liveness probes. Aliased at /readyz for Kubernetes-canonical clients.", "security": [], "responses": { "200": { "description": "Service is ready to accept traffic.", "content": { "application/json": { "schema": { "description": "Service is ready to accept traffic.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "503": { "description": "Service is not ready.", "content": { "application/problem+json": { "schema": { "description": "Service is not ready.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_ready" ] }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } }, "additionalProperties": false } } } } } } }, "/readyz": { "get": { "operationId": "readinessCheckKubernetes", "summary": "Readiness check (Kubernetes-canonical alias for /health/ready)", "tags": [ "Health" ], "description": "Behaves identically to /health/ready. Present for clients that follow the /healthz, /readyz, /livez convention.", "security": [], "responses": { "200": { "description": "Service is ready to accept traffic.", "content": { "application/json": { "schema": { "description": "Service is ready to accept traffic.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "503": { "description": "Service is not ready.", "content": { "application/problem+json": { "schema": { "description": "Service is not ready.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_ready" ] }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } }, "additionalProperties": false } } } } } } }, "/livez": { "get": { "operationId": "livenessCheck", "summary": "Liveness check", "tags": [ "Health" ], "description": "Trivial 200 response indicating the process is alive and serving HTTP. No database or dependency check. Use for Kubernetes liveness probes when you explicitly want to avoid cascading restarts on downstream outages.", "security": [], "responses": { "200": { "description": "Service process is alive.", "content": { "application/json": { "schema": { "description": "Service process is alive.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "alive" ] }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } } } } }, "/v1/conformance": { "get": { "operationId": "getConformance", "summary": "Server capability declaration", "tags": [ "Discovery" ], "description": "Declares which capabilities this AGLedger instance has wired up. No authentication required.", "security": [], "responses": { "200": { "description": "Server capability declaration — which features are wired on this install.", "content": { "application/json": { "schema": { "description": "Server capability declaration — which features are wired on this install.", "type": "object", "properties": { "capabilities": { "type": "object", "properties": { "recordLifecycle": { "type": "boolean" }, "twoPhaseGate": { "type": "boolean" }, "auditVault": { "type": "boolean" }, "hashChainIntegrity": { "type": "boolean" }, "ed25519Signatures": { "type": "boolean" }, "signingAlgorithms": { "type": "array", "items": { "type": "string" }, "description": "Signature algorithms this build can sign chain envelopes with. Ed25519 is the default; a non-default algorithm additionally requires the AGLEDGER_ALLOW_NON_DEFAULT_SIGNING_ALG opt-in at boot. Per-key algorithm resolution for verification lives at /v1/verification-keys." }, "delegationChains": { "type": "boolean" }, "cascadingGate": { "type": "boolean" }, "disputeResolution": { "type": "boolean" }, "reputationScoring": { "type": "boolean" }, "webhookDelivery": { "type": "boolean" }, "a2aProtocol": { "type": "boolean" }, "encryptedMode": { "type": "boolean" }, "euAiActCompliance": { "type": "boolean" }, "scittRegistration": { "type": "boolean", "description": "POST /v1/scitt/entries — register a customer-signed COSE_Sign1 Signed Statement against the per-org SCITT log, returns a Receipt." }, "signedStatementExport": { "type": "boolean", "description": "GET /v1/records/{id}/attestation — canonical COSE_Sign1 chain envelopes (application/cose-sequence). `?receipts=true` upgrades to a Transparent Statement sequence (Receipts attached at unprotected label 394)." }, "sigstoreBundleExport": { "type": "boolean", "description": "GET /v1/records/{id}/attestation.bundle — structural sigstore-bundle v0.3 projection for Rekor / in-toto consumers. Structural-only; cryptographic verification is /attestation." }, "coseMerkleReceipts": { "type": "boolean", "description": "SCITT Receipts (draft-ietf-cose-merkle-tree-proofs) — RFC 9162 inclusion proofs at unprotected label 396, available on /audit-export?receipts=true and /scitt/entries." }, "oidcWorkloadIdentity": { "type": "boolean", "description": "Direct-JWT admin auth on /v1/admin/* and JWT-exchange agent auth via /v1/auth/oidc/cert routes are wired. Acceptance is data-driven by `trusted_issuers` rows — `true` here means the surface exists; query GET /v1/admin/trusted-issuers for actual issuer registrations." }, "ephemeralCerts": { "type": "boolean", "description": "POST /v1/auth/oidc/cert route is wired — agents exchange an IdP JWT for a short-lived Ed25519-bound AGLedger cert. Cert TTL is min(now + maxCredentialTtlSeconds, jwt.exp); 10-min cap by default, 60s floor (sub-60s remaining returns 422). Acceptance requires a matching `trusted_issuers` row with `appliesTo: agent` or `any`." }, "trustedIssuers": { "type": "boolean", "description": "GET/POST/PATCH/DELETE /v1/admin/trusted-issuers routes are wired — platform-key registration of OIDC IdP allow-list. Required precondition for `oidcWorkloadIdentity` / `ephemeralCerts` to actually accept JWTs." }, "agentSignatureCoSign": { "type": "boolean", "description": "X-Agent-Signature + X-Agent-Signature-Content-Hash headers accepted on POST /v1/records, /v1/records/:id/transition, /v1/records/:id/completions. Cert-bound Ed25519 per-request co-signature carried into the COSE_Sign1 chain envelope as predicate.on_behalf_of.agent_signature. Honored only when the caller authenticated via an ephemeral cert." } }, "additionalProperties": false }, "contractTypes": { "type": "integer", "description": "Number of registered types" }, "schemasUrl": { "type": "string", "description": "URL to list all type schemas (criteria + evidence structure)" }, "settlementSignals": { "type": "array", "items": { "type": "string" }, "description": "Supported settlement signal types" }, "version": { "type": "string", "description": "AGLedger API version" } }, "additionalProperties": false } } } } } } }, "/lifecycle": { "get": { "operationId": "getLifecycle", "summary": "RecordRow and dispute state machines", "tags": [ "Discovery" ], "description": "Returns the complete state machine for record and dispute lifecycles, including valid transitions from each state and common paths. Agents should call this once to understand the state machine. No authentication required.", "security": [], "responses": { "200": { "description": "State machine definitions.", "content": { "application/json": { "schema": { "description": "State machine definitions.", "type": "object", "properties": { "record": { "type": "object", "additionalProperties": true }, "dispute": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } } } } }, "/status": { "get": { "operationId": "getPublicStatus", "summary": "Platform status", "tags": [ "Status" ], "description": "Returns the current operational status of AGLedger platform components. No authentication required. Designed for status pages, dashboards, and monitoring.", "security": [], "responses": { "200": { "description": "Current platform status.", "content": { "application/json": { "schema": { "description": "Current platform status.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "outage" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "operational", "degraded", "outage" ] }, "latencyMs": { "type": "number", "nullable": true } }, "additionalProperties": false } }, "uptime": { "type": "number" }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "summary": "LLM agent discovery document", "tags": [ "Discovery" ], "description": "Returns a Markdown document following the llms.txt standard (llmstxt.org) with instructions for AI agents consuming this API. Includes all active types (platform + org-scoped). The primary example is controlled by AGLEDGER_EXAMPLE_CONTRACT_TYPE.\n\n**Auth:** none (public endpoint)", "security": [], "responses": { "200": { "description": "Markdown document for LLM agent consumption.", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string", "description": "Markdown document for LLM agent consumption." } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFullTxt", "summary": "LLM agent discovery document (full version with schema details)", "tags": [ "Discovery" ], "description": "Returns an expanded Markdown document with full type details: record/completion schema fields, quickStart examples, and gate rules for every registered type. Larger than /llms.txt but gives agents everything they need in a single fetch.\n\n**Auth:** none (public endpoint)", "security": [], "responses": { "200": { "description": "Expanded Markdown document with schema details.", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string", "description": "Expanded Markdown document with schema details." } } } } } } }, "/v1/admin/discovery/reload": { "post": { "operationId": "adminReloadDiscovery", "summary": "Reload agent-discovery documents", "tags": [ "Admin" ], "description": "Busts the in-memory caches for /llms.txt and /llms-full.txt. The next fetch regenerates from current DB state. Schema create/deprecate operations already invalidate these caches automatically via LISTEN/NOTIFY — this endpoint is the manual escape hatch for operators who want to force a refresh.\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] }, { "adminOidcJwt": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reloaded": { "type": "boolean" }, "message": { "type": "string" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "required": [ "reloaded" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/predicates": { "get": { "operationId": "listPredicates", "summary": "Index of AGLedger in-toto predicate schemas", "tags": [ "Discovery" ], "description": "Returns one entry per AGLedger claim kind with the predicate type URI (used as `predicateType` in DSSE bundle exports) and the schema fetch URL on this deployment.\n\n**Auth:** none (public discovery endpoint).", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "kind", "predicateType", "schemaUrl" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "record-state", "settlement-signal", "vault-checkpoint", "org-read", "counter-attestation", "federation-projection", "schema-event" ] }, "predicateType": { "type": "string", "format": "uri" }, "schemaUrl": { "type": "string" } } } } } } } } } } } }, "/predicates/{kind}/v1": { "get": { "operationId": "getPredicateSchema", "summary": "JSON Schema for an AGLedger predicate kind", "tags": [ "Discovery" ], "description": "Returns the canonical JSON Schema (draft-2019-09) for the in-toto Statement predicate body emitted under `predicateType=https://agledger.ai/predicates/{kind}/v1`. Generated from the engine's body schema — never hand-written.\n\n**Auth:** none (public discovery endpoint).", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "in": "path", "name": "kind", "required": true } ], "security": [], "responses": { "200": { "description": "JSON Schema document (draft-2019-09).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "JSON Schema document (draft-2019-09)." } } } }, "400": { "description": "Bad Request — request failed JSON Schema validation (querystring / path params / body).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown predicate kind. See GET /predicates for the canonical list.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/.well-known/security.txt": { "get": { "operationId": "getSecurityTxt", "summary": "Security contact information (RFC 9116)", "tags": [ "Discovery" ], "description": "Returns a security.txt file per RFC 9116 with vulnerability reporting contact information, disclosure policy, and preferred language.\n\n**Auth:** none (public endpoint)", "security": [], "responses": { "200": { "description": "RFC 9116 security.txt document", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string", "description": "RFC 9116 security.txt document" } } } } } } }, "/v1/verification-keys": { "get": { "operationId": "listVerificationKeys", "summary": "List vault verification keys (public)", "tags": [ "Discovery" ], "description": "Returns all current and historical public keys used to sign Signed Statements, plus the COSE_Sign1 envelope/algorithm parameters so external auditors can independently verify hash-chained, signed audit chains without admin access, source code access, or full audit exports.\n\n**Auth:** none (public endpoint). Public keys are, by definition, public.\n\n**Algorithm resolution:** each key carries its own `algorithm` and `coseAlgorithm`; verify every entry with the algorithm of the key its `signingKeyId` resolves to. The document-level `coseAlgorithm`/`signatureAlgorithm` describe the currently-active key only. Every key is Ed25519 unless the operator explicitly opted into a non-default algorithm.\n\n**Verification workflow:** For each Signed Statement, pull the `cose_sign1` byte string from `/v1/records/{id}/audit-export` (base64-encoded) or `/v1/records/{id}/attestation` (raw CBOR). Resolve the entry's `signingKeyId` to a public key from this response, then verify the COSE_Sign1 signature per RFC 9052 §4.4: reconstruct `Sig_structure = [\"Signature1\", protected_bstr, h'', payload_bstr]`, deterministically CBOR-encode it (RFC 8949 §4.2.1), and verify with the key's algorithm. **Stock-library path:** any RFC 9052 implementation works — `go-cose`, `coset` (Rust), or `pycose` (pass `allow_unknown_attributes=True` for the private label −65537). The `signatureInputTemplate` field below documents the byte-level signing input so no AGLedger package is required. `@agledger/verify` (npm) is a turnkey alternative that consumes the same dump format the stock libs read; each key's `minVerifierVersion` names the minimum version able to verify it.", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "keyId": { "type": "string", "description": "SHA-256 fingerprint (16 hex chars). Matches the RFC 9421 `keyid` on ed25519 webhook signatures and the COSE_Sign1 protected-header kid." }, "algorithm": { "type": "string", "description": "Signature algorithm of THIS key (e.g. Ed25519). Authoritative per key: entries signed under a retired key verify with that key's algorithm, not the active one." }, "coseAlgorithm": { "type": "integer", "description": "COSE alg label for THIS key (RFC 9053; -8 = EdDSA). Authoritative per key: a chain entry's protected-header alg must equal the value for the key its kid resolves to, and a mismatch is a tamper signal, not an upgrade hint. Single integer today; may be ABSENT when this build cannot resolve the row's algorithm, so consumers must tolerate absence." }, "minVerifierVersion": { "type": "string", "description": "Minimum @agledger/verify version able to verify entries signed under this key. The algorithm support lives in that package's @agledger/verify-core dependency, so this floor is the @agledger/verify release that resolves a core carrying it under every install shape; an earlier version may happen to work depending on what its core resolves to." }, "publicKey": { "type": "string", "description": "Base64-encoded SPKI DER public key" }, "publicKeyRaw": { "type": "string", "description": "Base64 of the raw 32-byte Ed25519 public key, for raw-key verifiers (RFC 9421 / Standard-Webhooks-style). Present only on Ed25519 keys: a raw key carries no AlgorithmIdentifier, so other algorithms publish SPKI only." }, "status": { "type": "string", "enum": [ "active", "retired" ] }, "activatedAt": { "type": "string", "format": "date-time", "description": "Instant this key became the active signing key (RFC 3339, millisecond precision). Lower bound of the key's temporal-validity window: an entry whose write time precedes it was not signed by this key." }, "retiredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Instant this key was retired (RFC 3339, millisecond precision), or null while it is still active. Upper bound of the temporal-validity window. Compare against the entry's write time at full precision: rotation happens at an instant, not at a day boundary, so a key legitimately signs entries on its retirement day." } }, "required": [ "keyId", "algorithm", "publicKey", "status", "activatedAt", "retiredAt" ], "additionalProperties": false } }, "envelope": { "type": "string", "enum": [ "COSE_Sign1" ], "description": "Canonical chain envelope shape — RFC 9052 §4.4 (CBOR tag 18)." }, "payloadFormat": { "type": "string", "enum": [ "application/vnd.in-toto+cbor" ], "description": "Canonical COSE payload media type — in-toto v1 Statement in deterministic CBOR." }, "canonicalization": { "type": "string", "enum": [ "RFC8949-CDE" ], "description": "Deterministic CBOR encoding rule (RFC 8949 §4.2.1 Core Deterministic Encoding)." }, "coseAlgorithm": { "type": [ "null", "integer" ], "description": "COSE algorithm label (RFC 9053; -8 = EdDSA) of the currently-ACTIVE signing key only, or null when the active key cannot be resolved. Retained for existing consumers; never use it to verify an entry whose kid resolves to a different key. The per-key `coseAlgorithm` in `data` is authoritative." }, "signatureAlgorithm": { "type": [ "null", "string" ], "description": "Signature algorithm of the currently-ACTIVE signing key only, or null when the active key cannot be resolved. Retained for existing consumers; the per-key `algorithm` in `data` is authoritative." }, "signatureInputTemplate": { "type": "string", "description": "Recipe for the byte-level Ed25519 signing input on every chain entry. COSE_Sign1 envelopes sign over the RFC 9052 §4.4 Sig_structure: `Sig_structure = [\"Signature1\", protected_bstr, h'', payload_bstr]`, deterministically CBOR-encoded per RFC 8949 §4.2.1. Pull `cose_sign1` from `/v1/records/{id}/audit-export` (base64) or `/v1/records/{id}/attestation` (raw CBOR), reconstruct the Sig_structure with empty external_aad, deterministically encode, then Ed25519 verify against the public key resolved by the entry's `signingKeyId`. No AGLedger package required." } }, "required": [ "data", "envelope", "payloadFormat", "canonicalization", "coseAlgorithm", "signatureAlgorithm", "signatureInputTemplate" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/.well-known/agledger-vault-keys.json": { "get": { "operationId": "getWellKnownVaultKeys", "summary": "List vault verification keys (public)", "tags": [ "Discovery" ], "description": "Returns all current and historical public keys used to sign Signed Statements, plus the COSE_Sign1 envelope/algorithm parameters so external auditors can independently verify hash-chained, signed audit chains without admin access, source code access, or full audit exports.\n\n**Auth:** none (public endpoint). Public keys are, by definition, public.\n\n**Algorithm resolution:** each key carries its own `algorithm` and `coseAlgorithm`; verify every entry with the algorithm of the key its `signingKeyId` resolves to. The document-level `coseAlgorithm`/`signatureAlgorithm` describe the currently-active key only. Every key is Ed25519 unless the operator explicitly opted into a non-default algorithm.\n\n**Verification workflow:** For each Signed Statement, pull the `cose_sign1` byte string from `/v1/records/{id}/audit-export` (base64-encoded) or `/v1/records/{id}/attestation` (raw CBOR). Resolve the entry's `signingKeyId` to a public key from this response, then verify the COSE_Sign1 signature per RFC 9052 §4.4: reconstruct `Sig_structure = [\"Signature1\", protected_bstr, h'', payload_bstr]`, deterministically CBOR-encode it (RFC 8949 §4.2.1), and verify with the key's algorithm. **Stock-library path:** any RFC 9052 implementation works — `go-cose`, `coset` (Rust), or `pycose` (pass `allow_unknown_attributes=True` for the private label −65537). The `signatureInputTemplate` field below documents the byte-level signing input so no AGLedger package is required. `@agledger/verify` (npm) is a turnkey alternative that consumes the same dump format the stock libs read; each key's `minVerifierVersion` names the minimum version able to verify it.", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "keyId": { "type": "string", "description": "SHA-256 fingerprint (16 hex chars). Matches the RFC 9421 `keyid` on ed25519 webhook signatures and the COSE_Sign1 protected-header kid." }, "algorithm": { "type": "string", "description": "Signature algorithm of THIS key (e.g. Ed25519). Authoritative per key: entries signed under a retired key verify with that key's algorithm, not the active one." }, "coseAlgorithm": { "type": "integer", "description": "COSE alg label for THIS key (RFC 9053; -8 = EdDSA). Authoritative per key: a chain entry's protected-header alg must equal the value for the key its kid resolves to, and a mismatch is a tamper signal, not an upgrade hint. Single integer today; may be ABSENT when this build cannot resolve the row's algorithm, so consumers must tolerate absence." }, "minVerifierVersion": { "type": "string", "description": "Minimum @agledger/verify version able to verify entries signed under this key. The algorithm support lives in that package's @agledger/verify-core dependency, so this floor is the @agledger/verify release that resolves a core carrying it under every install shape; an earlier version may happen to work depending on what its core resolves to." }, "publicKey": { "type": "string", "description": "Base64-encoded SPKI DER public key" }, "publicKeyRaw": { "type": "string", "description": "Base64 of the raw 32-byte Ed25519 public key, for raw-key verifiers (RFC 9421 / Standard-Webhooks-style). Present only on Ed25519 keys: a raw key carries no AlgorithmIdentifier, so other algorithms publish SPKI only." }, "status": { "type": "string", "enum": [ "active", "retired" ] }, "activatedAt": { "type": "string", "format": "date-time", "description": "Instant this key became the active signing key (RFC 3339, millisecond precision). Lower bound of the key's temporal-validity window: an entry whose write time precedes it was not signed by this key." }, "retiredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Instant this key was retired (RFC 3339, millisecond precision), or null while it is still active. Upper bound of the temporal-validity window. Compare against the entry's write time at full precision: rotation happens at an instant, not at a day boundary, so a key legitimately signs entries on its retirement day." } }, "required": [ "keyId", "algorithm", "publicKey", "status", "activatedAt", "retiredAt" ], "additionalProperties": false } }, "envelope": { "type": "string", "enum": [ "COSE_Sign1" ], "description": "Canonical chain envelope shape — RFC 9052 §4.4 (CBOR tag 18)." }, "payloadFormat": { "type": "string", "enum": [ "application/vnd.in-toto+cbor" ], "description": "Canonical COSE payload media type — in-toto v1 Statement in deterministic CBOR." }, "canonicalization": { "type": "string", "enum": [ "RFC8949-CDE" ], "description": "Deterministic CBOR encoding rule (RFC 8949 §4.2.1 Core Deterministic Encoding)." }, "coseAlgorithm": { "type": [ "null", "integer" ], "description": "COSE algorithm label (RFC 9053; -8 = EdDSA) of the currently-ACTIVE signing key only, or null when the active key cannot be resolved. Retained for existing consumers; never use it to verify an entry whose kid resolves to a different key. The per-key `coseAlgorithm` in `data` is authoritative." }, "signatureAlgorithm": { "type": [ "null", "string" ], "description": "Signature algorithm of the currently-ACTIVE signing key only, or null when the active key cannot be resolved. Retained for existing consumers; the per-key `algorithm` in `data` is authoritative." }, "signatureInputTemplate": { "type": "string", "description": "Recipe for the byte-level Ed25519 signing input on every chain entry. COSE_Sign1 envelopes sign over the RFC 9052 §4.4 Sig_structure: `Sig_structure = [\"Signature1\", protected_bstr, h'', payload_bstr]`, deterministically CBOR-encoded per RFC 8949 §4.2.1. Pull `cose_sign1` from `/v1/records/{id}/audit-export` (base64) or `/v1/records/{id}/attestation` (raw CBOR), reconstruct the Sig_structure with empty external_aad, deterministically encode, then Ed25519 verify against the public key resolved by the entry's `signingKeyId`. No AGLedger package required." } }, "required": [ "data", "envelope", "payloadFormat", "canonicalization", "coseAlgorithm", "signatureAlgorithm", "signatureInputTemplate" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/.well-known/scitt-configuration": { "get": { "operationId": "getScittConfiguration", "summary": "SCITT spec discovery document", "tags": [ "SCITT", "Discovery" ], "description": "draft-ietf-scitt-scrapi §4 transparency configuration. Advertises the SCRAPI endpoints + key set this TS exposes plus the supported signing/registration algorithms. Unauthenticated so a SCITT-aware client can bootstrap without holding a key. Mirrors /llms.txt §SCRAPI for machine consumers.", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "registration_endpoint", "resolution_endpoint", "jwks_uri", "supported_signature_algorithms", "supported_registration_policies" ], "additionalProperties": false, "properties": { "issuer": { "type": "string", "description": "Issuer URL identifying this Transparency Service (matches AGLEDGER_EXTERNAL_URL)." }, "registration_endpoint": { "type": "string", "description": "POST /v1/scitt/entries — register a Signed Statement; 201 + Receipt." }, "resolution_endpoint": { "type": "string", "description": "GET /v1/scitt/entries/{entryId} — fetch a Transparent Statement with a freshly-issued Receipt." }, "checkpoint_endpoint": { "type": "string", "description": "GET /v1/scitt/checkpoint — signed tree head (root + tree size + signature)." }, "jwks_uri": { "type": "string", "description": "GET /.well-known/scitt-keys — TS verification keys as a CBOR COSE_KeySet." }, "supported_signature_algorithms": { "type": "array", "items": { "type": "string" }, "description": "COSE algorithm names this TS SIGNS WITH (Receipts, Transparent Statements, checkpoints). Registration is content-agnostic: POST /v1/scitt/entries does not verify Issuer signatures, so this list does not constrain what may be registered." }, "supported_registration_policies": { "type": "array", "items": { "type": "string" }, "description": "Registration policy identifiers. `accept-all` means the TS does not gate registration by issuer or subject — any well-formed COSE_Sign1 is accepted." }, "llms_txt": { "type": "string", "description": "Pointer to the human/LLM-readable discovery doc with worked examples." } } } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/.well-known/scitt-keys": { "get": { "operationId": "getScittKeySet", "summary": "TS verification keys as a CBOR COSE_KeySet", "tags": [ "SCITT", "Discovery" ], "description": "SCRAPI-required keyset endpoint. Returns every known vault signing key as a CBOR COSE_KeySet (array of COSE_Key maps per RFC 9052 §7). Unauthenticated; the JSON equivalent at `/v1/verification-keys` carries the same keys for non-SCITT consumers.", "security": [], "responses": { "200": { "description": "COSE_KeySet bytes.", "content": { "application/cbor": { "schema": { "type": "string", "format": "binary", "description": "COSE_KeySet bytes." } }, "application/problem+json": { "schema": { "type": "string", "format": "binary", "description": "COSE_KeySet bytes." } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/cbor": { "schema": { "$ref": "#/components/schemas/RateLimitError" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/cbor": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/.well-known/scitt-keys/{kid}": { "get": { "operationId": "getScittKeyByKid", "summary": "Single TS verification key as CBOR COSE_Key", "tags": [ "SCITT", "Discovery" ], "description": "Resolve one verification key by its hex `kid`. Returns a single CBOR COSE_Key map (NOT wrapped in an array). The schema `pattern` on `kid` rejects malformed values before the handler runs — non-hex inputs surface as Fastify validation errors (JSON), not CBOR problem details.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{16,}$", "maxLength": 128 }, "in": "path", "name": "kid", "required": true } ], "security": [], "responses": { "200": { "description": "COSE_Key bytes.", "content": { "application/cbor": { "schema": { "type": "string", "format": "binary", "description": "COSE_Key bytes." } }, "application/concise-problem-details+cbor": { "schema": { "type": "string", "format": "binary", "description": "COSE_Key bytes." } }, "application/problem+json": { "schema": { "type": "string", "format": "binary", "description": "COSE_Key bytes." } } } }, "400": { "description": "Bad Request — request failed JSON Schema validation (querystring / path params / body).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error envelope as application/concise-problem-details+cbor (RFC 9290).", "content": { "application/cbor": { "schema": { "description": "Error envelope as application/concise-problem-details+cbor (RFC 9290).", "type": "string", "format": "binary" } }, "application/concise-problem-details+cbor": { "schema": { "description": "Error envelope as application/concise-problem-details+cbor (RFC 9290).", "type": "string", "format": "binary" } }, "application/problem+json": { "schema": { "description": "Error envelope as application/concise-problem-details+cbor (RFC 9290).", "type": "string", "format": "binary" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/cbor": { "schema": { "$ref": "#/components/schemas/RateLimitError" } }, "application/concise-problem-details+cbor": { "schema": { "$ref": "#/components/schemas/RateLimitError" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/cbor": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/concise-problem-details+cbor": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/schemas": { "get": { "operationId": "listSchemas", "summary": "List available types", "tags": [ "Schemas" ], "description": "Returns type summaries — one row per type, showing the latest version and lifecycle status so the catalog is usable without per-type round-trips. Default view is ACTIVE only; pass `?includeDisabled=true` to see DISABLED types as well. Use `?orgId=` (with auth) to include that org's custom types.\n\n**Auth:** none — this is part of the always-on Agent Discovery Surface (alongside `/llms.txt`, `/openapi.json`, `/.well-known/agent-card.json`, `/v1/verification-keys`, `/v1/scope-profiles`). An unauthenticated `GET /v1/schemas` returns `200 { total: 0, data: [], nextSteps: [register one] }` on a fresh install rather than `401`, on purpose: LLM agents discover this Server's capabilities before they hold any credentials, and a 401 here would force a credential-fetch loop before the discovery flow can complete. To enumerate org-custom types the caller still needs a key (`?orgId=`); `POST /v1/schemas` for registration always requires auth.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "orgId", "required": false, "description": "Include this org's custom types (requires auth)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeDisabled", "required": false, "description": "Include DISABLED types in the response (default: ACTIVE only)." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of results to return" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Number of results to skip" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type identifier (e.g., acme-po-v1)" }, "version": { "type": "integer", "description": "Latest version number for this type" }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED" ], "description": "Lifecycle status — DISABLED types reject new records" }, "displayName": { "type": [ "null", "string" ], "description": "Human-readable name" }, "category": { "type": [ "null", "string" ], "description": "Customer-defined taxonomy label (no engine semantics) — e.g. `decision`, `delivery-attempt`, `incident_report`. Lets a newcomer triage the catalog by domain." }, "description": { "type": [ "null", "string" ], "description": "Truncated preview of the per-type description (max ~280 chars + ellipsis). Full text is on `GET /v1/schemas/{type}`. Lets a newcomer judge fit without N round-trips." }, "templateUrl": { "type": "string", "description": "URL to fetch a forkable template seeded from this type — the \"fork an existing type into your namespace\" verb. The returned template is freely editable (you can flip `additionalProperties:false` → `true` on the recordSchema if you need to extend with your own fields, edit the type name, swap displayName, etc.) and POST-able to `/v1/schemas` to register your own." }, "publisher": { "type": "string", "description": "Publisher label that owns this row. the schema catalog — list returns one row per (publisher, type) so callers can disambiguate before issuing scoped reads." }, "orgId": { "type": [ "null", "string" ], "format": "uuid", "description": "Owning org id, or `null` for platform-bundled types. Present only on platform-key reads without `?orgId=` — surfaces the org axis a platform admin needs to see what is registered where. Omitted on org-scoped reads." }, "defaultGateMode": { "type": [ "null", "string" ], "description": "Lifecycle discriminator — `auto` or `principal` for a principal-/auto-gated type, `null` for notarize-only / no-default-gate. Mirrors `defaultGateMode` on `GET /v1/schemas/{type}` so a newcomer can tell a gated type from a notarize-only one from the list row alone, without a per-type GET." } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of matching records (-1 when using cursor pagination)" }, "nextCursor": { "type": [ "null", "string" ], "description": "Cursor for the next page (null if no more results)" }, "hasMore": { "type": "boolean", "description": "Whether more results exist beyond this page" }, "recordRead": { "type": "object", "properties": { "leafIndex": { "type": "integer", "minimum": 0 }, "leafHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "signedCheckpointRef": { "type": [ "null", "string" ], "format": "uuid" } }, "required": [ "leafIndex", "leafHash", "signedCheckpointRef" ], "additionalProperties": false, "description": "SCITT-style inclusion-proof completion for org_admin_reads. Present only when the caller is a org-admin reading cross-party data." }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "400": { "description": "Bad Request — request failed JSON Schema validation (querystring / path params / body).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "registerSchema", "summary": "Register a custom type", "tags": [ "Schemas" ], "description": "Register a new type with custom record and completion JSON Schemas. Org auth creates org-scoped types; platform auth can register types in any org.\n\n**Auth:** admin, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "recordSchema" ], "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Custom type name. Customers own their entire type namespace within their org — no prefixes are reserved." }, "displayName": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 8000, "description": "Plain-English description of what this Type records and why. Write it as you would describe it to a colleague (2-4 paragraphs is fine). Example: \"Logs every time our procurement bot accepts a vendor quote — captures the supplier, the line items, and the bot's confidence score for the audit trail.\"" }, "category": { "type": "string", "maxLength": 100, "description": "Free-form taxonomy of what kind of artifact this Type produces — your label, your vocabulary. Examples customers have used: \"decision\", \"delivery-attempt\", \"telemetry-tick\", \"auth_attempt\", \"incident_report\". No engine semantics; it is exposed back on read and surfaced in /v1/schemas listings so agents can browse by domain." }, "recordSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for record criteria" }, "completionSchema": { "type": "object", "additionalProperties": true, "description": "Optional JSON Schema for completion evidence. Omit (or pass `{}`) when this Type does not have a completion phase — Records of such Types terminalize at `RECORDED` on create. Provide a structured schema to opt into the completion + verdict lifecycle." }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string", "description": "Generic gate rule ID" }, "criteriaPath": { "type": "string", "description": "Dot-notation path in criteria. Required when `valueType` is anything other than `expression`. For `valueType: 'expression'` the field is accepted but ignored — expression rules read from the `criteria.*` / `evidence.*` / `tolerance.*` bindings directly. Omit it on expression rules to avoid stale paths persisting on the rule row." }, "evidencePath": { "type": "string", "description": "Dot-notation path in evidence. Required when `valueType` is anything other than `expression`. For `valueType: 'expression'` the field is accepted but ignored. Omit it on expression rules." }, "toleranceField": { "type": "string", "description": "Tolerance band field name" }, "maxTolerance": { "type": "number", "minimum": 0, "description": "Cap on the per-record tolerance a caller may pass for this rule. `0` forbids any tolerance (the rule is an undodgeable threshold gate); a positive value pins the widest band a record may declare. Omitted = uncapped. The cap applies in whatever unit the tolerance key uses (percent for `*Pct`/`*_pct` keys, absolute otherwise). Enforced with 400 at every tolerance write (create, bulk, update)." }, "valueType": { "type": "string", "enum": [ "number", "denomination", "string", "boolean", "datetime", "expression" ], "description": "Value type for comparison logic. Use \"expression\" for safe expression-based rules." }, "expression": { "type": "string", "maxLength": 500, "description": "Safe expression string (required when valueType is \"expression\"). **Must evaluate to a boolean** — true = check passes, false = check fails. A non-boolean result (number, string, etc) is rejected with \"Expression evaluated to , expected boolean\"; wrap arithmetic in a comparison (e.g. `evidence.amount <= criteria.budget`, not `evidence.amount`). Top-level variable bindings are: `criteria.*`, `evidence.*`, `tolerance.*`, `metadata.*`, `record.*`, `parent.*` (the parent record's server-truth projection: signed `created_at`/`activated_at`/`fulfilled_at` timestamps + id/status/type; on a parent-less record any parent.* reference fails the check with a clear error, fail-closed, rather than trusting a supplied copy). NOT `completion.evidence.*` or `record.criteria.*` — these are the top-level scope objects, not nested. Helpers: abs, min, max, len, sum, contains, lower, daysBetween, coalesce. See GET /v1/schemas/meta-schema for the full binding spec + helper signatures." } }, "required": [ "ruleId", "valueType" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "valueType": { "enum": [ "expression" ] } }, "required": [ "valueType" ] }, "then": { "required": [ "expression" ] }, "else": { "required": [ "criteriaPath", "evidencePath" ] } } ] }, "maxItems": 20 }, "compatibilityMode": { "type": "string", "enum": [ "none", "backward", "forward", "full" ] }, "defaultShare": { "type": "boolean", "description": "V1 sharing default for records of this contract type. Omit to inherit the global `AGLEDGER_DEFAULT_SHARE` (which itself defaults to `true`). Per-record `share` overrides this. Row-only metadata; NOT canonicalized into the manifest digest, so federation digest-echo treats `defaultShare`-divergent installs as identical schemas." }, "defaultGateMode": { "type": "string", "enum": [ "auto", "principal" ], "description": "Default gate mode applied to records of this type when the create payload omits `gateMode`. Omit for the engine default (`auto` — rules engine renders the verdict and auto-settles). Set `principal` when this type's purpose is a principal-held verdict, so records created from the quickStart cannot silently auto-settle; the quickStart then surfaces `gateMode` explicitly too. An explicit per-record `gateMode` always wins. Row-only metadata; NOT canonicalized into the manifest digest." }, "coSignRequired": { "type": "boolean", "description": "V1 Additive E — opt into bilateral co-signed Settlement Signals for records of this contract type. Omit/`false` for single-signature signals (V1-FRAME default — firing Server signs alone). `true` = before firing a terminal Settlement Signal, the firing Server first POSTs a co-sign request to the counterparty's `/federation/v1/co-sign-requests` and attaches the returned counter-signature to the signal as `counterSignature`. Use for high-value or regulated dual-control flows. Per-contract-type only (no per-record override). Row-only metadata; NOT canonicalized into the manifest digest." }, "flipRecordStatusOnDispute": { "type": "boolean", "description": "When `true` (default), opening a dispute against a record of this type flips `record.status` to DISPUTED while the dispute is in flight; the record returns to its pre-dispute status on resolve/withdraw via `dispute_pre_status`. When `false`, the record stays at its current status and the dispute is observable only via `disputeStatus`/`disputeId`/`disputeCount` on the record body (plus `?hasDispute=` / `?disputeStatus=` query filters on /v1/records). Set to `false` when \"FULFILLED at time T\" must remain a historical fact even during dispute (compliance/audit framing). Row-only metadata; NOT canonicalized into the manifest digest." }, "federateDisputes": { "type": "boolean", "description": "When `true` (default), disputes on federated records of this contract type propagate to peers: the originator's dispute lifecycle emits federation outbound jobs that update the peer's record body (`disputeStatus`/`hasDispute`/`disputeCount`/`grounds`/`context`) and write a receiver chain entry. When `false`, disputes stay local to the originator's chain; the peer's record body is unchanged until a RELEASE Settlement Signal fires on overturn. Default-on fits the intra-org federation case (the typical V1 deployment). Cross-org deployments wanting strict boundary flip to `false` per type. Row-only metadata; NOT canonicalized into the manifest digest." }, "publisher": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", "description": "Optional publisher label. Omit (or pass `local`) for engine-authored schemas — that's the standalone-Server default. Pass a non-`local` label (e.g. `trust-circle-a`) to publish under a coordinated label that two federated Servers can agree on out-of-band, so cross-peer schemaRef matching resolves on both sides. The label is part of the manifest digest, so the same body published under two different labels produces two different rows." } }, "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] }, { "agentEphemeralCert": [] } ], "responses": { "201": { "description": "Custom type registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "version": { "type": "integer" }, "orgId": { "type": [ "null", "string" ], "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "category": { "type": [ "null", "string" ], "maxLength": 100, "description": "Free-form taxonomy of what kind of artifact this Type produces. Customer-defined; no engine semantics." }, "compatibilityMode": { "type": "string" }, "status": { "type": "string" }, "publisher": { "type": "string", "description": "Publisher label. \"local\" for engine-authored, anything else for imported." }, "manifestDigest": { "type": "string", "description": "sha256: federation-comparable digest." }, "trustClass": { "type": "string", "enum": [ "local", "imported" ] }, "federatable": { "type": "boolean" }, "defaultShare": { "type": [ "null", "boolean" ], "description": "V1 sharing default for this contract type. `null` = inherit the global `AGLEDGER_DEFAULT_SHARE`. Row-only metadata, NOT in the canonical manifest body." }, "defaultGateMode": { "type": [ "null", "string" ], "description": "Default gate mode (`auto` or `principal`) for records of this type when the create payload omits `gateMode`. `null` = engine default (`auto`). Row-only metadata, NOT in the canonical manifest body." }, "coSignRequired": { "type": [ "null", "boolean" ], "description": "V1 Additive E — bilateral co-signed Settlement Signal opt-in. `null`/`false` = signals fire single-sig; `true` = firing Server requests a counter-signature before firing. Row-only metadata, NOT in the canonical manifest body." }, "flipRecordStatusOnDispute": { "type": "boolean", "description": "Per-type opt-in for whether opening a dispute flips `record.status` to DISPUTED in flight. Default true. See the full doc on this field in the `getSchemaResponse`." }, "federateDisputes": { "type": "boolean", "description": "Per-type opt-out for dispute propagation across federation. Default true. See the full doc on this field in the `getSchemaResponse`." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "quickStart": { "type": [ "null", "object" ], "properties": { "criteria": { "type": "object", "additionalProperties": true, "description": "Minimal valid criteria example — copy and modify. Synthesized from the record schema (prefers the JSON Schema standard `examples` keyword; falls back to required fields with type-driven placeholders)." }, "evidence": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Minimal valid completion evidence example — copy and modify. Null on notarize-only Types (no completion phase, no /completions call to make)." }, "tolerance": { "type": [ "null", "object" ], "additionalProperties": { "type": "number" }, "description": "Copy-pasteable tolerance example — one entry per registered fieldMapping. The key is the fieldMapping`s `toleranceField` (when declared) or its `ruleId` (the natural fallback both engine and validator accept). Keys ending in `Pct`/`_pct` apply as percentage tolerance (example value 5 = ±5%); other keys apply as absolute tolerance. Null when the type has no fieldMappings registered." }, "gateMode": { "type": "string", "enum": [ "auto", "principal" ], "description": "Present only when the type declares a `defaultGateMode` — include it in the POST /v1/records payload (the engine also applies it when you omit `gateMode`, so the copy-paste path is safe either way). Absent = engine default `auto` (rules engine renders the verdict and auto-settles at completion time; no principal verdict window)." } }, "description": "Copy-pasteable starter Record + completion bodies derived from the registered schemas. Returned inline on POST /v1/schemas so the caller does not need a follow-up GET." }, "rulesConfig": { "type": "object", "properties": { "type": { "type": "string" }, "syncRuleIds": { "type": "array", "items": { "type": "string" }, "description": "Rule IDs applied synchronously during Phase 1 structural validation" }, "asyncRuleIds": { "type": "array", "items": { "type": "string" }, "description": "Rule IDs applied asynchronously during Phase 2 gate evaluation" }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "toleranceField": { "type": "string" }, "maxTolerance": { "type": "number" }, "valueType": { "type": "string" }, "expression": { "type": "string" } }, "additionalProperties": false }, "description": "Custom field mappings for gate rules" }, "commissionSourceField": { "type": "string", "description": "Dot-notation path to the commission base value field in criteria" } }, "description": "The live gate rule wiring (syncRuleIds, asyncRuleIds, fieldMappings) echoed on write so the caller can confirm what the engine will evaluate without a follow-up GET. Same nested shape as GET /v1/schemas/{type}." }, "warnings": { "type": "array", "description": "Keywords in the submitted schemas that this validator does not enforce, so they are ignored. Usually a misspelling (`maxLenght` for `maxLength`), which is worth acting on: the constraint the author intended is not applied and every value passes. Absent when there are none. Prefix a deliberate annotation with `x-` to keep it out of this list.", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Location of the keyword within the schema (empty string = root)." }, "keyword": { "type": "string", "description": "The unrecognized keyword." }, "message": { "type": "string", "description": "What was ignored, and the closest recognized keyword when one is near." } }, "additionalProperties": false } }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "description": "Custom type registered." } } } }, "400": { "description": "Invalid schema or naming.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name conflicts with an existing version for the same publisher/org.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/schemas/meta-schema": { "get": { "operationId": "getMetaSchema", "summary": "Get schema constraint specification", "tags": [ "Schemas" ], "description": "Returns the full constraint specification for the AGLedger meta-schema validator. Use this to configure local IDE validation (e.g., VS Code JSON Schema settings), build custom linting, or power schema authoring tools.\n\n**Recommended OSS tools for local authoring:**\n- **VS Code**: Point `json.schemas` at the constraints from this endpoint\n- **json-editor** (github.com/json-editor/json-editor): Embeddable React schema editor\n- **Stoplight Studio** (free tier): Visual JSON Schema design (draft-07)\n\n**Auth:** none (public endpoint)", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "constraints": { "type": "object", "properties": { "maxDepth": { "type": "integer" }, "maxNodes": { "type": "integer" }, "maxSizeBytes": { "type": "integer" }, "maxCombinerEntries": { "type": "integer" }, "rootTypeMustBe": { "type": "string" }, "rootMustHaveRequired": { "type": "boolean" }, "blockedKeywords": { "type": "array", "items": { "type": "string" } }, "supportedApplicators": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema applicator keywords the validator walks and enforces in custom schemas — conditional (`if`/`then`/`else`), combiners (`allOf`/`anyOf`/`oneOf`, bounded by `maxCombinerEntries`), and `not`. See `examples.conditionalCompletion` for a worked if/then/else." }, "noIdAllowed": { "type": "boolean" } } }, "allowedFormats": { "type": "array", "items": { "type": "string" } }, "allowedRefs": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "properties": { "contractTypeMaxLength": { "type": "integer" }, "maxFieldMappings": { "type": "integer" }, "ruleIdPattern": { "type": "string" }, "ruleIdMaxLength": { "type": "integer" }, "reservedPrefixes": { "type": "array", "items": { "type": "string" } } } }, "fieldMappingValueTypes": { "type": "array", "items": { "type": "string" } }, "fieldMappingValueTypeSpec": { "type": "object", "additionalProperties": { "type": "object", "properties": { "evidenceShape": { "type": "string" }, "comparator": { "type": "string" } }, "required": [ "evidenceShape", "comparator" ], "additionalProperties": false }, "description": "Per-valueType evidence shape + comparator semantics. Read this BEFORE designing fieldMappings — `denomination` requires `{amount, currency}`, `string` does strict equality (use `valueType: expression` with `contains`/`lower` for pattern match)." }, "expressionHelpers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "signature": { "type": "string" }, "semantics": { "type": "string" } }, "required": [ "signature", "semantics" ], "additionalProperties": false }, "description": "Helper functions callable inside an expression, keyed by name. `signature` is the call shape; `semantics` states the edge behavior (invalid-input result, rounding direction, coercion) to read BEFORE relying on a helper in a gate rule. Example: `daysBetween` counts whole elapsed 24h periods between UTC instants (floored, order-independent), NOT calendar days, and returns 0 on unparseable dates." }, "expressionBindings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Top-level variable bindings available inside an expression-type field mapping. Each key is the path root (write `.`); each value documents what that scope object contains." }, "expressionMustReturnBoolean": { "type": "boolean", "description": "Hard contract: an expression MUST evaluate to true/false. Numeric or string results are rejected. Wrap arithmetic in a comparison." }, "expressionLimits": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "maxAstNodes": { "type": "integer" }, "maxAstDepth": { "type": "integer" }, "maxOperations": { "type": "integer" }, "allowedContexts": { "type": "array", "items": { "type": "string" } } } }, "builtinRuleIds": { "type": "array", "items": { "type": "string" }, "description": "RESERVED — these `ruleId` strings are reserved by the engine for built-in semantic checks (e.g. `quantity_match`, `price_ceiling`). Do NOT use them as `ruleId` values in custom `fieldMappings` — registration will reject with 400. Pick a different identifier (kebab-case, your-domain prefix recommended)." }, "verbVocabulary": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "Verb vocabulary keyed by valueType. A `ruleId` shaped as `:` is a semantic claim — the prefix MUST equal the declared `valueType`, and the verb MUST appear in this table. Registry rejects unknown verbs at registration with the allowed list. Free-form ruleIds (no colon) fall through to each valueType's default verb in `verbVocabularyDefaults`." }, "verbVocabularyDefaults": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Default verb per valueType when a fieldMapping uses a free-form `ruleId` (no `:` prefix). e.g. `{ number: \"exact-match\", datetime: \"max-inclusive\", string: \"exact\", ... }`." }, "sharedSchemas": { "type": "object", "additionalProperties": true }, "examples": { "type": "object", "properties": { "minimalRecord": { "type": "object", "additionalProperties": true }, "minimalCompletion": { "type": "object", "additionalProperties": true }, "conditionalCompletion": { "type": "object", "additionalProperties": true, "description": "Worked if/then/else example — conditional-required completion evidence (\"if determination=denied, require denialBasis\"). Fully enforced at Phase-1 structural validation; the same shape also works on a recordSchema." } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/schemas/_blank": { "get": { "operationId": "getBlankTemplate", "summary": "Get a blank schema template", "tags": [ "Schemas" ], "description": "Returns a minimal registration-ready skeleton with TODO placeholders. Default is **notarize-only** (`completionSchema: {}`, `fieldMappings: []`) — the 90% path. Pass `?withCompletion=true` for the judgment-mode skeleton (completion-bearing schema + a sample fieldMapping).\n\n**Auth:** none (public)", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "withCompletion", "required": false, "description": "Return the judgment-mode skeleton (populated completionSchema + fieldMappings) instead of the notarize-only default." } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceType": { "type": [ "null", "string" ] }, "template": { "type": "object", "properties": { "type": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "recordSchema": { "type": "object", "additionalProperties": true }, "completionSchema": { "type": "object", "additionalProperties": true }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "toleranceField": { "type": "string" }, "maxTolerance": { "type": "number" }, "valueType": { "type": "string" }, "expression": { "type": "string" } }, "additionalProperties": false } } } } } } } } }, "400": { "description": "Bad Request — request failed JSON Schema validation (querystring / path params / body).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/schemas/{type}/template": { "get": { "operationId": "getSchemaTemplate", "summary": "Fork an existing type into your namespace", "tags": [ "Schemas" ], "description": "Returns a registration-ready skeleton seeded from the specified type — the \"fork an existing type into your namespace\" verb. Preserves the source type's `recordSchema` / `completionSchema` / `fieldMappings` (the rule wiring stays verbatim — `:` ruleIds are not renamed); rewrites `type` / `displayName` / `description` to TODO markers in the response.\n\n**The returned template is freely editable.** Rename `type` to land it in your namespace, flip `recordSchema.additionalProperties: false` → `true` (or edit `required[]` / `properties`) if you need to extend the source's structure with your own fields, swap `displayName`, then POST to `/v1/schemas`. Use this when a catalogue type is structurally close to your domain but its record fields don't match (e.g. a carrier-payout type whose `recordSchema` you want to adapt for invoice-approval).\n\n**Discoverable on every list row.** `GET /v1/schemas` surfaces `templateUrl` per row so an agent surveying the catalog finds the fork path without reading the OpenAPI.\n\n**Auth:** none (public)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "orgId", "required": false, "description": "Org scope for custom types" }, { "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$" }, "in": "query", "name": "publisher", "required": false, "description": "Publisher label scope. When omitted and >1 publisher offers this type in the org, the response is 422 with the candidate list." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "type", "required": true, "description": "Type identifier (e.g., notarize-generic-v1)" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceType": { "type": [ "null", "string" ] }, "template": { "type": "object", "properties": { "type": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "recordSchema": { "type": "object", "additionalProperties": true }, "completionSchema": { "type": "object", "additionalProperties": true }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "toleranceField": { "type": "string" }, "maxTolerance": { "type": "number" }, "valueType": { "type": "string" }, "expression": { "type": "string" } }, "additionalProperties": false } } } } } } } } }, "400": { "description": "Bad Request — request failed JSON Schema validation (querystring / path params / body).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown type.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/schemas/{type}/manifest": { "get": { "operationId": "getSchemaManifest", "summary": "Get the import-ready manifest for a type", "tags": [ "Schemas" ], "description": "Returns the canonical manifest body for this Server's registration of `{type}`, shaped exactly as `POST /v1/schemas/import` accepts it. The bytes are JCS-canonicalized before hashing so the returned `manifestDigest` matches the digest a peer would compute on import. Use this to mirror a schema to a federated peer without out-of-band coordination beyond agreeing on a non-`local` publisher label.\n\n**Auth:** none (public endpoint, same posture as `GET /v1/schemas/{type}`).", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "orgId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "publisher", "required": false, "description": "Disambiguate when multiple publishers offer the same type in this org." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "type", "required": true, "description": "Type identifier (e.g., notarize-generic-v1)" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "manifest", "manifestDigest" ], "properties": { "manifest": { "type": "object", "additionalProperties": true, "description": "The canonical manifest body. Send under `{ \"manifest\": }` to `POST /v1/schemas/import` on a peer Server; the peer will compute the same digest." }, "manifestDigest": { "type": "string", "description": "sha256: over the JCS-canonicalized manifest." }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "400": { "description": "Bad Request — request failed JSON Schema validation (querystring / path params / body).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown type.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Ambiguous publisher; pass `?publisher=` to disambiguate.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/schemas/{type}": { "get": { "operationId": "getSchema", "summary": "Get record and completion schemas for a type", "tags": [ "Schemas" ], "description": "Returns the JSON Schema definitions for both record criteria and completion evidence for the specified type. Use `?orgId=` to resolve org-scoped custom types. Use `?format=template` to get a registration-ready skeleton.\n\n**Auth:** none (public endpoint)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "orgId", "required": false, "description": "Org scope for custom types" }, { "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$" }, "in": "query", "name": "publisher", "required": false, "description": "Publisher label scope. When omitted and >1 publisher offers this type in the org, the response is 422 with the candidate list." }, { "schema": { "type": "string", "enum": [ "template" ] }, "in": "query", "name": "format", "required": false, "description": "Set to \"template\" to get a registration-ready skeleton" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "type", "required": true, "description": "Type identifier (e.g., notarize-generic-v1)" } ], "security": [], "responses": { "200": { "description": "RecordRow and completion JSON Schema definitions plus gate rules for the type. Use the quickStart field for copy-pasteable example payloads.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "version": { "type": "integer", "description": "Schema revision number" }, "latestVersion": { "type": "integer", "description": "Latest active revision number" }, "displayName": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "category": { "type": [ "null", "string" ], "maxLength": 100, "description": "Free-form taxonomy of what kind of artifact this Type produces (e.g. \"decision\", \"delivery-attempt\"). Customer-defined; no engine semantics." }, "publisher": { "type": "string", "description": "Publisher label that owns this row. \"local\" for engine-authored; anything else for file-imported schemas." }, "manifestDigest": { "type": "string", "description": "sha256: of the JCS-canonicalized manifest. Federation peers compare schemas by this value." }, "trustClass": { "type": "string", "enum": [ "local", "imported" ], "description": "How this row was authored. Federation digest-echo treats both identically." }, "federatable": { "type": "boolean", "description": "Whether this engine exposes the schema to federated peer hubs. Row-only metadata; not in the canonical manifest." }, "defaultShare": { "type": [ "null", "boolean" ], "description": "V1 sharing default for records of this contract type. `null` = inherit the global `AGLEDGER_DEFAULT_SHARE`; `true`/`false` is an explicit per-type decision. Per-record `share` overrides this. Row-only metadata, NOT in the canonical manifest body." }, "defaultGateMode": { "type": [ "null", "string" ], "description": "Default gate mode (`auto` or `principal`) applied to records of this type when the create payload omits `gateMode`. `null` = engine default (`auto`). An explicit per-record `gateMode` always wins. Types whose purpose is the principal-held verdict set `principal` here so the copy-paste path cannot silently auto-settle. Row-only metadata, NOT in the canonical manifest body." }, "coSignRequired": { "type": [ "null", "boolean" ], "description": "V1 Additive E — bilateral co-signed Settlement Signal opt-in. `null`/`false` = signals fire single-signature (firing Server only, V1-FRAME default). `true` = before firing, the firing Server requests a counter-signature from the counterparty's `/federation/v1/co-sign-requests` and attaches it to the Settlement Signal as `counterSignature`. Per-contract-type only (no per-record override). Row-only metadata, NOT in the canonical manifest body." }, "flipRecordStatusOnDispute": { "type": "boolean", "description": "When `true` (default), opening a dispute against a record of this type flips `record.status` to DISPUTED while the dispute is in flight (restored to pre-status on resolve/withdraw). When `false`, the record stays at its current status (most often FULFILLED/REMEDIATED/FAILED) and the dispute is observable only via `disputeStatus`/`disputeId`/`disputeCount` on the record body plus `?hasDispute=` and `?disputeStatus=` query filters. Compliance-minded customers (where FULFILLED at time T must remain a historical fact) set this `false` per type. Row-only metadata, NOT in the canonical manifest body." }, "federateDisputes": { "type": "boolean", "description": "When `true` (default), disputes on federated records of this contract type propagate to peers: the originator's dispute lifecycle (open/resolve/withdraw + tier transitions) emits federation outbound jobs that update the peer's record body (`disputeStatus`, `hasDispute`, `disputeCount`, `grounds`, `context`) and write a receiver chain entry. When `false`, disputes stay local to the originator's chain — the peer's record body is unchanged until a RELEASE Settlement Signal fires on overturn. Default-on fits the intra-org federation case (the typical V1 deployment) where counterparty reconciliation benefits from full dispute visibility. Cross-org deployments wanting strict boundary flip to `false` per type. Row-only metadata, NOT in the canonical manifest body." }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED" ], "description": "Lifecycle status: ACTIVE or DISABLED" }, "quickStart": { "type": [ "null", "object" ], "properties": { "criteria": { "type": "object", "additionalProperties": true, "description": "Minimal valid criteria example — copy and modify. Synthesized from the record schema (prefers the JSON Schema standard `examples` keyword; falls back to required fields with type-driven placeholders)." }, "evidence": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Minimal valid completion evidence example — copy and modify. Null on notarize-only Types (no completion phase, no /completions call to make)." }, "tolerance": { "type": [ "null", "object" ], "additionalProperties": { "type": "number" }, "description": "Copy-pasteable tolerance example — one entry per registered fieldMapping. The key is the fieldMapping`s `toleranceField` (when declared) or its `ruleId` (the natural fallback both engine and validator accept). Keys ending in `Pct`/`_pct` apply as percentage tolerance (example value 5 = ±5%); other keys apply as absolute tolerance. Null when the type has no fieldMappings registered." }, "gateMode": { "type": "string", "enum": [ "auto", "principal" ], "description": "Present only when the type declares a `defaultGateMode` — include it in the POST /v1/records payload (the engine also applies it when you omit `gateMode`, so the copy-paste path is safe either way). Absent = engine default `auto` (rules engine renders the verdict and auto-settles at completion time; no principal verdict window)." } }, "description": "Copy-pasteable example payloads for this type. null when neither schema is registered (rare; a type without either schema cannot be used)." }, "recordSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for record criteria" }, "completionSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for completion evidence" }, "rulesConfig": { "type": "object", "properties": { "type": { "type": "string" }, "syncRuleIds": { "type": "array", "items": { "type": "string" }, "description": "Rule IDs applied synchronously during Phase 1 structural validation" }, "asyncRuleIds": { "type": "array", "items": { "type": "string" }, "description": "Rule IDs applied asynchronously during Phase 2 gate evaluation" }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "toleranceField": { "type": "string" }, "maxTolerance": { "type": "number" }, "valueType": { "type": "string" }, "expression": { "type": "string" } }, "additionalProperties": false }, "description": "Custom field mappings for gate rules" }, "commissionSourceField": { "type": "string", "description": "Dot-notation path to the commission base value field in criteria" } }, "description": "Gate rules configuration for the type." } }, "description": "RecordRow and completion JSON Schema definitions plus gate rules for the type. Use the quickStart field for copy-pasteable example payloads." } } } }, "400": { "description": "Bad Request — request failed JSON Schema validation (querystring / path params / body).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown type.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Agent keys: 500 req/min. Admin keys: 1,000 req/min. Defaults tunable via RATE_LIMIT_AGENT / RATE_LIMIT_ADMIN.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteContractType", "summary": "Permanently delete a type", "tags": [ "Schemas" ], "description": "Physically removes a type and all its versions from the registry, scoped to the publisher the call resolves to. Two preconditions, both must pass:\n\n1. All versions under that publisher must be DISABLED (409 `STATUS_NOT_DISABLED` otherwise)\n2. No record still depends on the rows being removed (409 `RECORDS_REFERENCE_TYPE` otherwise). A record pins the exact registration it was written against, so this counts the records bound to THIS publisher's rows, not every record sharing the type name. Records carrying no pin (written before every create path recorded one, or received as federated projections) cannot be attributed to any publisher and so block a delete under every label. The 409 body splits the two counts as `pinnedRecords` and `unattributableRecords`.\n\nDelete is for a registration nothing was ever written against. The way to retire one that has records is `PATCH /v1/schemas/{type}/disable`, which stops new records binding to it and leaves the existing ones able to resolve the schema their criteria and evidence were validated against.\n\n**Auth:** admin (own schemas), platform (any schema).", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "orgId", "required": false, "description": "Org scope (platform only)" }, { "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$" }, "in": "query", "name": "publisher", "required": false, "description": "Publisher label scope. When omitted and >1 publisher offers this type in the org, the response is 422 with the candidate list." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "type", "required": true, "description": "Type identifier (e.g., notarize-generic-v1)" } ], "security": [ { "bearerAuth": [] }, { "agentEphemeralCert": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "publisher": { "type": "string", "description": "Publisher label this delete targeted, always the one the call resolved to. Rows under any OTHER publisher of the same type are untouched and still in the catalog: this field, not the absence of the type, is what says which registration went away." }, "versionsDeleted": { "type": "integer" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "400": { "description": "Bad Request — request failed JSON Schema validation (querystring / path params / body).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Type not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Precondition failed. Response includes a machine-readable `reason`: `STATUS_NOT_DISABLED` or `RECORDS_REFERENCE_TYPE`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The type exists under more than one publisher in this org, so the target is ambiguous. The body lists the candidates in `publishers`; re-issue with ?publisher=