{ "openapi": "3.0.3", "info": { "title": "AGLedger API", "description": "AGLedger provides accountability infrastructure for AI agents — built for audit, governance, and enterprise 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 **Governance Sidecar** (MCP proxy) sits between agents and tools, recording activity without code modifications. The **Compliance Export** assembles enterprise-wide audit data for regulators, auditors, and GRC tooling.\n\n**Key capabilities:** 9 currency-agnostic contract types (AOAP), 16-state mandate lifecycle, delegation chains (up to depth 5) with cascading verification, A2A protocol support (AgentCard discovery + JSON-RPC 2.0), dual operating modes (cleartext with server verification, encrypted with self-verification), 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- **enterprise** -- mandate owners who define acceptance criteria\n- **agent** -- task executors who submit receipt evidence (can also act as principals in delegation chains)\n- **platform** -- payment platforms that receive settlement signals\n\nNew accounts start in sandbox mode with restricted access. Three paths to full access: email verification, A2A AgentCard verification (agents), or auto-graduation after first successful mandate verification.\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\nWebhook payloads are signed with HMAC-SHA256. The signature header format is:\n\n```\nX-AGLedger-Signature: t=,v1=\n```\n\nThe signed payload is `${timestamp}.${rawBody}`. Verify by recomputing the HMAC with your webhook secret and comparing using a constant-time comparison. Reject any delivery where `t` is more than 300 seconds (5 minutes) old to prevent replay attacks.\n\nEach delivery also includes an `X-AGLedger-Delivery: ` header for consumer-side idempotency.\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 and trust level: sandbox accounts get 200 req/min, standalone agents get 500 req/min, enterprise accounts (and their approved agents) get 1,000 req/min. 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.0.0", "contact": { "name": "AGLedger", "url": "https://agledger.ai" }, "license": { "name": "Proprietary" } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key for enterprise, agent, or platform roles. Include as `Bearer ` in the Authorization header." }, "platformAuth": { "type": "http", "scheme": "bearer", "description": "Platform-role API key (ach_pla_*). Required for all /admin/* endpoints." }, "portalSession": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Portal session token (agl_sess_*). Issued via magic link or password login." }, "federationBearer": { "type": "http", "scheme": "bearer", "description": "Short-lived federation bearer token issued by the Hub during Gateway registration and refreshed on heartbeat. Not an API key — tokens are opaque and rotate automatically." } }, "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 'contractType'?\")" }, "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 (eval, enterprise, federation)" }, "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 mandate/receipt validation (e.g., schema lookup URL)" }, "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required fields for the request body (present on 400 for mandate/receipt creation)" }, "optionalFields": { "type": "array", "items": { "type": "string" }, "description": "Optional fields for the request body (present on 400 for mandate/receipt creation)" }, "examplePayload": { "type": "object", "additionalProperties": true, "description": "Example request body for mandate/receipt creation" }, "schemaUrl": { "type": "string", "description": "URL to the contract type schema for field reference" }, "contractType": { "type": "string", "description": "Contract type related to the validation error" }, "currentState": { "type": "string", "description": "Current state of the resource" }, "attemptedTransition": { "type": "string", "description": "Transition that was attempted" }, "validTransitions": { "type": "array", "items": { "type": "string" }, "description": "Valid transitions from the current state" }, "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" } }, "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 'contractType'?\")" }, "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 (eval, enterprise, federation)" }, "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 mandate/receipt validation (e.g., schema lookup URL)" }, "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required fields for the request body (present on 400 for mandate/receipt creation)" }, "optionalFields": { "type": "array", "items": { "type": "string" }, "description": "Optional fields for the request body (present on 400 for mandate/receipt creation)" }, "examplePayload": { "type": "object", "additionalProperties": true, "description": "Example request body for mandate/receipt creation" }, "schemaUrl": { "type": "string", "description": "URL to the contract type schema for field reference" }, "contractType": { "type": "string", "description": "Contract type related to the validation error" }, "currentState": { "type": "string", "description": "Current state of the resource" }, "attemptedTransition": { "type": "string", "description": "Transition that was attempted" }, "validTransitions": { "type": "array", "items": { "type": "string" }, "description": "Valid transitions from the current state" }, "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" }, "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" } }, "additionalProperties": false }, "Mandate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "agentId": { "type": [ "null", "string" ], "format": "uuid" }, "principalType": { "type": "string", "enum": [ "enterprise", "agent" ], "description": "Who created this mandate: enterprise (traditional) or agent (agent-to-agent)" }, "principalAgentId": { "type": [ "null", "string" ], "format": "uuid", "description": "Agent ID of the principal (when principalType=agent)" }, "acceptanceStatus": { "type": [ "null", "string" ], "description": "Proposal status: PROPOSED, ACCEPTED, REJECTED, COUNTER_PROPOSED" }, "acceptanceRespondedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "When the performer responded to the proposal" }, "parentMandateId": { "type": [ "null", "string" ], "format": "uuid", "description": "Parent mandate ID in a delegation chain" }, "chainDepth": { "type": "integer", "description": "Depth in delegation chain (0 = top-level)" }, "rootMandateId": { "type": [ "null", "string" ], "format": "uuid", "description": "Root mandate in the delegation chain" }, "childMandateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of child mandates in the delegation chain (present on single-mandate fetch only)" }, "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 (full server verification) or encrypted (self-verification)" }, "verificationMode": { "type": "string", "enum": [ "auto", "principal", "gated" ], "description": "Verification mode: auto (rules engine auto-settles), principal (hold for principal verdict), gated (run rules then hold for principal)" }, "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": [ "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)" }, "contractType": { "type": "string" }, "contractVersion": { "type": "string" }, "schemaUrl": { "type": "string", "description": "URL to the contract type schema for discovering expected criteria and evidence structure (e.g., /v1/schemas/ACH-PROC-v1)" }, "platform": { "type": "string" }, "platformRef": { "type": [ "null", "string" ] }, "projectRef": { "type": [ "null", "string" ], "description": "External project reference for grouping mandates" }, "externalTaskId": { "type": [ "null", "string" ], "description": "External task system ID for linking mandates to CI/CD pipelines, RPA tasks, or workflow engines" }, "enforcementOverrides": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Per-mandate enforcement overrides (Phase 3). Can only relax enterprise settings." }, "projectId": { "type": [ "null", "string" ], "format": "uuid", "description": "Project this mandate belongs to (nullable)" }, "dependsOn": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Informational dependency references to other mandate IDs (no activation gating)" }, "status": { "type": "string", "enum": [ "CREATED", "PROPOSED", "ACTIVE", "PROCESSING", "REVISION_REQUESTED", "FULFILLED", "FAILED", "REMEDIATED", "EXPIRED", "CANCELLED", "REJECTED" ], "description": "Lifecycle state: CREATED (not yet active), PROPOSED (agent proposal pending), ACTIVE (awaiting work), PROCESSING (receipt/verification in progress), REVISION_REQUESTED, FULFILLED, FAILED, REMEDIATED, EXPIRED, CANCELLED, REJECTED" }, "criteria": { "type": "object", "additionalProperties": true, "description": "Acceptance criteria matching the contract type JSON Schema" }, "tolerance": { "type": "object", "additionalProperties": true, "description": "Tolerance bands for semantic verification (e.g., quantity deviation %)" }, "deadline": { "type": [ "null", "string" ], "format": "date-time", "description": "ISO 8601 deadline after which the mandate auto-expires" }, "verificationOutcome": { "type": [ "null", "string" ], "enum": [ "PASS", "FAIL", null ], "description": "Phase 2 verification outcome (null until verification completes). Check verificationChecks for per-rule details." }, "verificationChecks": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Detailed per-rule verification 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" }, "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 receipt was rejected." }, "lastVerdictAt": { "type": [ "null", "string" ], "format": "date-time", "description": "When the most recent verdict or revision request was made" }, "submissionCount": { "type": "integer", "description": "Number of receipts submitted (incremented on each accepted receipt)" }, "maxSubmissions": { "type": [ "null", "integer" ], "description": "Maximum allowed receipt submissions (null = unlimited)" }, "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" }, "receiptHint": { "type": [ "null", "object" ], "properties": { "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required field names for receipt evidence submission" }, "schemaUrl": { "type": "string", "description": "URL to the full receipt schema" } }, "additionalProperties": false, "description": "Lightweight hint showing required receipt evidence fields. Use schemaUrl for the full JSON Schema with types and descriptions." }, "nextActions": { "type": "array", "items": { "type": "string" }, "description": "Valid next actions from the current state (e.g., register, activate, cancel, submit-receipt)" }, "validTransitions": { "type": "array", "items": { "type": "string", "enum": [ "CREATED", "PROPOSED", "ACTIVE", "PROCESSING", "REVISION_REQUESTED", "FULFILLED", "FAILED", "REMEDIATED", "EXPIRED", "CANCELLED", "REJECTED" ] }, "description": "Valid target states from the current state" }, "noOp": { "type": "boolean", "description": "True when the requested transition was already in the target state (idempotent no-op)" }, "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 enterprise 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 mandate (present on single-mandate fetch only)" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls based on current mandate state. Guides AI agents through the mandate lifecycle without requiring prior knowledge of the state machine." } }, "additionalProperties": false }, "Receipt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "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" }, "mandateStatus": { "type": "string", "description": "Current mandate status after this receipt was processed" }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls after receipt submission (e.g., check verification status)" } }, "additionalProperties": false }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "description": "HTTPS endpoint that receives webhook deliveries" }, "eventTypes": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Event type filter — null means all events are delivered, array restricts to listed types only." }, "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" }, "createdAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "HMAC-SHA256 signing secret (returned ONCE on creation/rotation -- store it securely)" }, "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" }, "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" }, "eventType": { "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": "HMAC-SHA256 signature header sent with the delivery" }, "requestBody": { "type": [ "null", "string" ], "description": "Raw JSON body sent to the endpoint — the exact bytes signed by the HMAC signature" }, "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" }, "mandateId": { "type": "string", "format": "uuid" }, "initiatedByRole": { "type": "string", "description": "Role of the dispute initiator (enterprise or agent)" }, "initiatedById": { "type": "string", "format": "uuid" }, "grounds": { "type": "string", "description": "Dispute grounds category" }, "context": { "type": [ "null", "string" ], "description": "Free-text context explaining the dispute" }, "status": { "type": "string", "description": "OPEN, TIER_2_REVIEW, TIER_3_ARBITRATION, RESOLVED, or DISMISSED" }, "currentTier": { "type": "integer", "description": "Current dispute tier (1 = auto, 2 = manual review, 3 = binding arbitration)" }, "outcome": { "type": [ "null", "string" ], "description": "Resolution outcome: UPHELD, OVERTURNED, PARTIALLY_UPHELD, or DISMISSED" }, "resolutionRationale": { "type": [ "null", "string" ], "description": "Explanation of the resolution decision" }, "feeChargedTo": { "type": [ "null", "string" ], "description": "Party charged the arbitration fee (Tier 3 only)" }, "feeAmount": { "type": [ "null", "string" ], "description": "Arbitration fee amount (Tier 3 only)" }, "feeCurrency": { "type": [ "null", "string" ], "description": "Currency of the arbitration fee (e.g., USD, EUR)" }, "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" }, "contractType": { "type": "string", "description": "Contract type this score applies to" }, "reliabilityScore": { "type": [ "null", "number" ], "description": "Task completion reliability (0-100)" }, "accuracyScore": { "type": [ "null", "number" ], "description": "Evidence accuracy vs mandate criteria (0-100)" }, "efficiencyScore": { "type": [ "null", "number" ], "description": "Time-to-completion efficiency (0-100)" }, "compositeScore": { "type": [ "null", "number" ], "description": "Weighted composite of all dimensions (0-100)" }, "confidenceLevel": { "type": [ "null", "number" ], "description": "Statistical confidence (0-1); tightens as transaction volume grows" }, "totalMandates": { "type": "integer", "description": "Total mandates assigned to this agent for this contract type" }, "totalVerified": { "type": "integer", "description": "Number of mandates with completed verification" }, "totalPassed": { "type": "integer", "description": "Number of mandates that passed verification" }, "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 }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string" } }, "additionalProperties": false }, "EnterpriseAgent": { "type": "object", "properties": { "enterpriseId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "approved", "suspended", "revoked" ] }, "approvedBy": { "type": [ "null", "string" ] }, "approvedAt": { "type": "string", "format": "date-time" }, "suspendedAt": { "type": [ "null", "string" ], "format": "date-time" }, "revokedAt": { "type": [ "null", "string" ], "format": "date-time" }, "reason": { "type": [ "null", "string" ] } }, "additionalProperties": false } } }, "paths": { "/metrics": { "get": { "operationId": "getMetrics", "summary": "Prometheus metrics", "tags": [ "Observability" ], "description": "Returns Prometheus-format metrics. No authentication required.", "security": [], "responses": { "200": { "description": "Prometheus metrics in text format.", "content": { "application/json": { "schema": { "description": "Prometheus metrics in text format.", "type": "string" } } } } } } }, "/schemas": { "get": { "operationId": "listSchemas", "summary": "List available contract types", "tags": [ "Schemas" ], "description": "Returns the list of available contract type identifiers. Use `?enterpriseId=` to include enterprise-custom types alongside built-in types.\n\n**Auth:** none (public endpoint)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Filter by enterprise (includes built-in types)" }, { "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": "string", "description": "Contract type identifier" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "registerSchema", "summary": "Register a custom contract type", "tags": [ "Schemas" ], "description": "Register a new contract type with custom mandate and receipt JSON Schemas. Enterprise auth creates enterprise-scoped types. Platform auth can create built-in types.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contractType", "mandateSchema", "receiptSchema" ], "properties": { "contractType": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Custom contract type name (must NOT match /^ach[_-]/i)" }, "displayName": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "category": { "type": "string", "maxLength": 50 }, "mandateSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for mandate criteria" }, "receiptSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for receipt evidence" }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string", "description": "Generic verification rule ID" }, "criteriaPath": { "type": "string", "description": "Dot-notation path in criteria (ignored for expression type)" }, "evidencePath": { "type": "string", "description": "Dot-notation path in evidence (ignored for expression type)" }, "toleranceField": { "type": "string", "description": "Tolerance band field name" }, "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\")" } }, "required": [ "ruleId", "criteriaPath", "evidencePath", "valueType" ], "additionalProperties": false }, "maxItems": 20 }, "compatibilityMode": { "type": "string", "enum": [ "NONE", "BACKWARD", "FORWARD", "FULL" ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Custom contract type registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "version": { "type": "integer" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "category": { "type": [ "null", "string" ] }, "compatibilityMode": { "type": "string" }, "status": { "type": "string" }, "isBuiltin": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "description": "Custom contract type registered." } } } }, "400": { "description": "Invalid schema or naming.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name conflicts with built-in type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/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" } }, "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" } }, "expressionHelpers": { "type": "array", "items": { "type": "string" } }, "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" } }, "sharedSchemas": { "type": "object", "additionalProperties": true }, "examples": { "type": "object", "properties": { "minimalMandate": { "type": "object", "additionalProperties": true }, "minimalReceipt": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/_blank": { "get": { "operationId": "getBlankTemplate", "summary": "Get a blank schema template", "tags": [ "Schemas" ], "description": "Returns a minimal registration-ready skeleton with TODO placeholders.\n\n**Auth:** none (public)", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceType": { "type": [ "null", "string" ] }, "template": { "type": "object", "properties": { "contractType": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "mandateSchema": { "type": "object", "additionalProperties": true }, "receiptSchema": { "type": "object", "additionalProperties": true }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "valueType": { "type": "string" } } } } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}/template": { "get": { "operationId": "getSchemaTemplate", "summary": "Get a schema template derived from an existing type", "tags": [ "Schemas" ], "description": "Returns a registration-ready skeleton pre-populated from the specified contract type.\n\n**Auth:** none (public)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise scope for custom types" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceType": { "type": [ "null", "string" ] }, "template": { "type": "object", "properties": { "contractType": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "mandateSchema": { "type": "object", "additionalProperties": true }, "receiptSchema": { "type": "object", "additionalProperties": true }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "valueType": { "type": "string" } } } } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown contract type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}": { "get": { "operationId": "getSchema", "summary": "Get mandate and receipt schemas for a contract type", "tags": [ "Schemas" ], "description": "Returns the JSON Schema definitions for both mandate criteria and receipt evidence for the specified contract type. Use `?enterpriseId=` to resolve enterprise-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": "enterpriseId", "required": false, "description": "Enterprise scope for custom types" }, { "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": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "security": [], "responses": { "200": { "description": "Mandate and receipt JSON Schema definitions plus verification rules for the contract type. Use the quickStart field for copy-pasteable example payloads.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contractType": { "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" ] }, "isBuiltin": { "type": "boolean" }, "status": { "type": "string", "description": "Lifecycle status: ACTIVE, DEPRECATED, or DELETED" }, "quickStart": { "type": "object", "properties": { "criteria": { "type": "object", "additionalProperties": true, "description": "Minimal valid criteria example — copy and modify" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Minimal valid receipt evidence example — copy and modify" } }, "description": "Copy-pasteable example payloads for this contract type." }, "mandateSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for mandate criteria" }, "receiptSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for receipt evidence" }, "rulesConfig": { "type": "object", "properties": { "contractType": { "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 semantic verification" }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "toleranceField": { "type": "string" }, "valueType": { "type": "string" }, "expression": { "type": "string" } }, "additionalProperties": false }, "description": "Custom field mappings for verification rules" }, "commissionSourceField": { "type": "string", "description": "Dot-notation path to the commission base value field in criteria" } }, "description": "Verification rules configuration for the contract type." } }, "description": "Mandate and receipt JSON Schema definitions plus verification rules for the contract type. Use the quickStart field for copy-pasteable example payloads." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown contract type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteContractType", "summary": "Delete a contract type", "tags": [ "Schemas" ], "description": "Marks all versions of a contract type as DELETED. Deleted types do not count against the 50-type limit.\n\nBy default, requires all versions to be DEPRECATED first. Use `?force=true` to delete regardless.\n\n**Auth:** enterprise (own schemas), platform (any schema).", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "force", "required": false, "description": "Delete even if ACTIVE versions exist" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise scope (platform only)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "contractType": { "type": "string" }, "versionsDeleted": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Contract type not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Active versions remain. Deprecate first or use ?force=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}/rules": { "get": { "operationId": "getRules", "summary": "Get verification rules config for a contract type", "tags": [ "Schemas" ], "description": "Returns the verification rules configuration for the specified contract type.\n\n**Auth:** none (public endpoint for built-in types; auth required for enterprise-scoped)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise scope for custom types" }, { "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": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "security": [], "responses": { "200": { "description": "Verification rules configuration for the contract type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contractType": { "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 semantic verification" }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "toleranceField": { "type": "string" }, "valueType": { "type": "string" }, "expression": { "type": "string" } }, "additionalProperties": false }, "description": "Custom field mappings for verification rules" }, "commissionSourceField": { "type": "string", "description": "Dot-notation path to the commission base value field in criteria" } }, "description": "Verification rules configuration for the contract type." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown contract type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}/validate": { "post": { "operationId": "validateReceipt", "summary": "Dry-run receipt evidence validation", "tags": [ "Schemas" ], "description": "Validates receipt evidence against the contract type receipt schema without creating a receipt.\n\n**Auth:** none (public endpoint for built-in types; auth required for enterprise-scoped)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evidence" ], "properties": { "evidence": { "type": "object", "additionalProperties": true, "description": "Evidence payload to validate against the receipt schema" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise scope for custom types" }, { "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": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "security": [], "responses": { "200": { "description": "Validation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the evidence conforms to the receipt schema" }, "errors": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "message": { "type": "string" }, "instancePath": { "type": "string" }, "schemaPath": { "type": "string" } }, "additionalProperties": true }, "description": "Validation errors (null when valid is true)" } }, "description": "Validation result." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/preview": { "post": { "operationId": "previewSchema", "summary": "Preview schema registration (dry run)", "tags": [ "Schemas" ], "description": "Full dry-run of the registration flow without persisting. Returns structured validation results including compiled schema info or detailed errors. Use this to iterate on schemas before registering.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contractType", "mandateSchema", "receiptSchema" ], "properties": { "contractType": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Custom contract type name (must NOT match /^ach[_-]/i)" }, "displayName": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "category": { "type": "string", "maxLength": 50 }, "mandateSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for mandate criteria" }, "receiptSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for receipt evidence" }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string", "description": "Generic verification rule ID" }, "criteriaPath": { "type": "string", "description": "Dot-notation path in criteria (ignored for expression type)" }, "evidencePath": { "type": "string", "description": "Dot-notation path in evidence (ignored for expression type)" }, "toleranceField": { "type": "string", "description": "Tolerance band field name" }, "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\")" } }, "required": [ "ruleId", "criteriaPath", "evidencePath", "valueType" ], "additionalProperties": false }, "maxItems": 20 }, "compatibilityMode": { "type": "string", "enum": [ "NONE", "BACKWARD", "FORWARD", "FULL" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Error category: META_SCHEMA, AJV_COMPILE, NAMING, FIELD_MAPPING, COMPATIBILITY" }, "message": { "type": "string" }, "path": { "type": "string" } } } }, "compiled": { "type": "object", "properties": { "mandateProperties": { "type": "array", "items": { "type": "string" } }, "mandateRequired": { "type": "array", "items": { "type": "string" } }, "receiptProperties": { "type": "array", "items": { "type": "string" } }, "receiptRequired": { "type": "array", "items": { "type": "string" } }, "ruleIds": { "type": "array", "items": { "type": "string" } }, "fieldMappingCount": { "type": "integer" }, "compatibilityCheck": { "type": [ "null", "object" ], "properties": { "mandate": { "type": "object", "properties": { "compatible": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string" }, "breaking": { "type": "boolean" }, "detail": { "type": "string" } } } } } }, "receipt": { "type": "object", "properties": { "compatible": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string" }, "breaking": { "type": "boolean" }, "detail": { "type": "string" } } } } } } } }, "estimatedVersion": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/import": { "post": { "operationId": "importSchema", "summary": "Import a schema package", "tags": [ "Schemas" ], "description": "Imports a schema export payload into this environment. Re-validates all schemas for security. Use `?dryRun=true` to validate without persisting.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "exportVersion", "exportedAt", "contractType", "compatibilityMode", "versions" ], "properties": { "exportVersion": { "type": "integer" }, "exportedAt": { "type": "string", "format": "date-time" }, "contractType": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "compatibilityMode": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "type": "string" }, "mandateSchema": { "type": "object", "additionalProperties": true }, "receiptSchema": { "type": "object", "additionalProperties": true }, "rulesConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "sharedSchemas": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "dryRun", "required": false, "description": "If true, validate without persisting" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Error category: META_SCHEMA, AJV_COMPILE, NAMING, FIELD_MAPPING, COMPATIBILITY" }, "message": { "type": "string" }, "path": { "type": "string" } } } }, "wouldCreate": { "type": "object", "properties": { "contractType": { "type": "string" }, "versions": { "type": "array", "items": { "type": "integer" } } } } } } } } }, "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "object", "properties": { "contractType": { "type": "string" }, "versionsCreated": { "type": "array", "items": { "type": "integer" } }, "subjectIds": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid schema or format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Type exists with different content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}/diff": { "get": { "operationId": "diffSchemaVersions", "summary": "Diff two schema versions", "tags": [ "Schemas" ], "description": "Returns a structured diff between two schema versions, including breaking change analysis.\n\n**Auth:** none (public for built-in types); auth required for enterprise-scoped", "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "from", "required": true, "description": "Source version number" }, { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "to", "required": true, "description": "Target version number" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise scope for custom types" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "contractType": { "type": "string" }, "from": { "type": "object", "properties": { "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" } } }, "to": { "type": "object", "properties": { "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" } } }, "mandate": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string" }, "breaking": { "type": "boolean" }, "detail": { "type": "string" } } } } } }, "receipt": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string" }, "breaking": { "type": "boolean" }, "detail": { "type": "string" } } } } } }, "overallCompatibility": { "type": "object", "properties": { "backward": { "type": "boolean" }, "forward": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}/export": { "post": { "operationId": "exportSchema", "summary": "Export a contract type for environment promotion", "tags": [ "Schemas" ], "description": "Exports a complete schema package including all versions and shared schemas. Use with `POST /v1/schemas/import` to promote schemas between environments.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "versions", "required": false, "description": "Comma-separated version numbers (default: all)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "exportVersion": { "type": "integer" }, "exportedAt": { "type": "string", "format": "date-time" }, "contractType": { "type": "string" }, "displayName": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "category": { "type": [ "null", "string" ] }, "compatibilityMode": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "type": "string" }, "mandateSchema": { "type": "object", "additionalProperties": true }, "receiptSchema": { "type": "object", "additionalProperties": true }, "rulesConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "sharedSchemas": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}/versions": { "get": { "operationId": "getSchemaVersions", "summary": "Get version history for a contract type", "tags": [ "Schemas" ], "description": "Returns all schema revisions for a contract type.\n\n**Auth:** none (public endpoint)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise scope for custom types" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "version": { "type": "integer" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "category": { "type": [ "null", "string" ] }, "compatibilityMode": { "type": "string" }, "status": { "type": "string" }, "isBuiltin": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}/versions/{version}": { "get": { "operationId": "getSchemaVersion", "summary": "Get a specific schema revision", "tags": [ "Schemas" ], "description": "Returns a specific schema revision with full schema content.\n\n**Auth:** none (public endpoint)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise scope for custom types" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contractType", "required": true }, { "schema": { "type": "integer", "minimum": 1 }, "in": "path", "name": "version", "required": true } ], "security": [], "responses": { "200": { "description": "Mandate and receipt JSON Schema definitions plus verification rules for the contract type. Use the quickStart field for copy-pasteable example payloads.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contractType": { "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" ] }, "isBuiltin": { "type": "boolean" }, "status": { "type": "string", "description": "Lifecycle status: ACTIVE, DEPRECATED, or DELETED" }, "quickStart": { "type": "object", "properties": { "criteria": { "type": "object", "additionalProperties": true, "description": "Minimal valid criteria example — copy and modify" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Minimal valid receipt evidence example — copy and modify" } }, "description": "Copy-pasteable example payloads for this contract type." }, "mandateSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for mandate criteria" }, "receiptSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema for receipt evidence" }, "rulesConfig": { "type": "object", "properties": { "contractType": { "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 semantic verification" }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "criteriaPath": { "type": "string" }, "evidencePath": { "type": "string" }, "toleranceField": { "type": "string" }, "valueType": { "type": "string" }, "expression": { "type": "string" } }, "additionalProperties": false }, "description": "Custom field mappings for verification rules" }, "commissionSourceField": { "type": "string", "description": "Dot-notation path to the commission base value field in criteria" } }, "description": "Verification rules configuration for the contract type." } }, "description": "Mandate and receipt JSON Schema definitions plus verification rules for the contract type. Use the quickStart field for copy-pasteable example payloads." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "patchSchemaVersion", "summary": "Update schema version lifecycle", "tags": [ "Schemas" ], "description": "Deprecate or delete a schema version.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "DEPRECATED", "DELETED" ] }, "compatibilityMode": { "type": "string", "enum": [ "NONE", "BACKWARD", "FORWARD", "FULL" ] } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise scope for custom types" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contractType", "required": true }, { "schema": { "type": "integer", "minimum": 1 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "version": { "type": "integer" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "category": { "type": [ "null", "string" ] }, "compatibilityMode": { "type": "string" }, "status": { "type": "string" }, "isBuiltin": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/schemas/{contractType}/check-compatibility": { "post": { "operationId": "checkSchemaCompatibility", "summary": "Check schema compatibility", "tags": [ "Schemas" ], "description": "Dry-run compatibility check against the latest version.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mandateSchema", "receiptSchema" ], "properties": { "mandateSchema": { "type": "object", "additionalProperties": true }, "receiptSchema": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "contractType", "required": true, "description": "Contract type identifier (e.g., ACH-PROC-v1)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "mandate": { "type": "object", "properties": { "compatible": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string" }, "breaking": { "type": "boolean" }, "detail": { "type": "string" } } } } } }, "receipt": { "type": "object", "properties": { "compatible": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string" }, "breaking": { "type": "boolean" }, "detail": { "type": "string" } } } } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/schemas/cache/flush": { "post": { "operationId": "flushSchemaCache", "summary": "Flush schema cache", "tags": [ "Admin" ], "description": "Emergency cache invalidation for schema registry.\n\n**Auth:** platform only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "flushed": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/.well-known/agent-card.json": { "get": { "operationId": "getAgentCard", "summary": "A2A Agent Card", "tags": [ "A2A Protocol" ], "description": "Returns the A2A Agent Card describing the AGLedger capabilities, skills (contract types), and authentication requirements. This is the standard A2A discovery endpoint.\n\n**Auth:** None (public)", "security": [], "responses": { "200": { "description": "A2A Agent Card.", "content": { "application/json": { "schema": { "description": "A2A Agent Card.", "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/agent.json": { "get": { "operationId": "getAgentCard", "summary": "A2A Agent Card", "tags": [ "A2A Protocol" ], "description": "Returns the A2A Agent Card describing the AGLedger capabilities, skills (contract types), and authentication requirements. This is the standard A2A discovery endpoint.\n\n**Auth:** None (public)", "security": [], "responses": { "200": { "description": "A2A Agent Card.", "content": { "application/json": { "schema": { "description": "A2A Agent Card.", "type": "object", "additionalProperties": true } } } } } } }, "/a2a": { "post": { "operationId": "a2aJsonRpc", "summary": "A2A JSON-RPC endpoint", "tags": [ "A2A Protocol" ], "description": "Google A2A protocol JSON-RPC 2.0 endpoint. Supports `message/send`, `tasks/get`, and `tasks/cancel` methods.\n\n**Supported intents via `message/send`:**\n- `create_mandate` — Create a new mandate (enterprise auth)\n- `submit_receipt` — Submit receipt evidence (agent auth)\n- `get_status` — Get mandate status with receipts as artifacts\n- `transition` — Transition mandate state (register, activate, settle, refund, cancel)\n\n**Auth:** Bearer token (enterprise, agent, or platform)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method", "id" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "method": { "type": "string", "minLength": 1 }, "params": { "type": "object", "additionalProperties": true }, "id": { "type": [ "string", "integer" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response (success or error).", "content": { "application/json": { "schema": { "description": "JSON-RPC 2.0 response (success or error).", "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "result": { "type": [ "null", "object" ], "additionalProperties": true }, "error": { "type": [ "null", "object" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": [ "null", "object" ], "additionalProperties": true } }, "additionalProperties": false }, "id": { "type": [ "null", "string", "integer" ] } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/register": { "post": { "operationId": "registerGateway", "summary": "Register a Gateway with the Hub", "tags": [ "Federation" ], "description": "Register a new Gateway instance using a registration token and RFC 9421 proof-of-possession. Returns Hub public keys and a short-lived bearer token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "registrationToken", "organizationId", "signingPublicKey", "encryptionPublicKey", "endpointUrl", "revocationSecret", "timestamp", "nonce", "signature" ], "additionalProperties": false, "properties": { "registrationToken": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1, "maxLength": 255 }, "displayName": { "type": "string", "maxLength": 255 }, "signingPublicKey": { "type": "string", "minLength": 1 }, "encryptionPublicKey": { "type": "string", "minLength": 1 }, "endpointUrl": { "type": "string", "format": "uri" }, "capabilities": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "revocationSecret": { "type": "string", "minLength": 16, "maxLength": 256 }, "timestamp": { "type": "string", "format": "date-time" }, "nonce": { "type": "string", "minLength": 16, "maxLength": 64 }, "signature": { "type": "string", "minLength": 1 } } } } } }, "security": [], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "gatewayId", "hubSigningPublicKey", "hubEncryptionPublicKey", "bearerToken", "bearerTokenExpiresAt", "registeredAt" ], "properties": { "gatewayId": { "type": "string" }, "hubSigningPublicKey": { "type": "string" }, "hubEncryptionPublicKey": { "type": "string" }, "bearerToken": { "type": "string" }, "bearerTokenExpiresAt": { "type": "string", "format": "date-time" }, "registeredAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/heartbeat": { "post": { "operationId": "federationHeartbeat", "summary": "Gateway heartbeat", "tags": [ "Federation" ], "description": "Send heartbeat with agent/mandate counts. Returns a fresh bearer token and any revocations since last heartbeat. Accepts expired tokens.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gatewayId", "agentCount", "mandateCount", "timestamp" ], "additionalProperties": false, "properties": { "gatewayId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agentCount": { "type": "integer", "minimum": 0 }, "mandateCount": { "type": "integer", "minimum": 0 }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ack", "serverTime", "bearerToken", "bearerTokenExpiresAt", "revocations" ], "properties": { "ack": { "type": "boolean" }, "serverTime": { "type": "string", "format": "date-time" }, "bearerToken": { "type": "string" }, "bearerTokenExpiresAt": { "type": "string", "format": "date-time" }, "revocations": { "type": "array", "items": { "type": "object", "required": [ "gatewayId", "revokedAt" ], "properties": { "gatewayId": { "type": "string" }, "revokedAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "nullable": true } } } }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/agents": { "post": { "operationId": "registerFederationAgent", "summary": "Register an agent in the federation directory", "tags": [ "Federation" ], "description": "Register a local agent in the Hub agent directory with its supported contract types.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "contractTypes" ], "additionalProperties": false, "properties": { "agentId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contractTypes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "displayName": { "type": "string", "maxLength": 255 } } } } } }, "security": [ { "federationBearer": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "registered" ], "properties": { "registered": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listFederationAgents", "summary": "List agents in the federation directory", "tags": [ "Federation" ], "description": "Query the Hub agent directory. Optionally filter by contract type. Cursor-paginated.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "contractType", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "agentId", "gatewayId", "contractTypes", "registeredAt" ], "properties": { "agentId": { "type": "string", "format": "uuid" }, "gatewayId": { "type": "string", "format": "uuid" }, "contractTypes": { "type": "array", "items": { "type": "string" } }, "displayName": { "type": "string", "nullable": true }, "registeredAt": { "type": "string", "format": "date-time" } } } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } } } } } } } }, "/federation/v1/catch-up": { "get": { "operationId": "federationCatchUp", "summary": "Fetch missed audit entries for partition recovery", "tags": [ "Federation" ], "description": "Returns audit log entries for the requesting gateway since a given chain position. Enables automatic recovery after network partitions.", "parameters": [ { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "sincePosition", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "in": "query", "name": "limit", "required": false } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "entryType", "payloadHash", "chainPosition", "alg", "createdAt" ], "properties": { "id": { "type": "string" }, "entryType": { "type": "string" }, "gatewayId": { "type": "string", "format": "uuid", "nullable": true }, "mandateId": { "type": "string", "format": "uuid", "nullable": true }, "payload": { "type": "object", "additionalProperties": true }, "payloadHash": { "type": "string" }, "previousHash": { "type": "string", "nullable": true }, "chainPosition": { "type": "integer" }, "alg": { "type": "string" }, "signature": { "type": "string", "nullable": true }, "signatureAlg": { "type": "string", "nullable": true }, "signingKeyId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "hasMore": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/stream": { "get": { "operationId": "federationStream", "summary": "Real-time SSE event stream", "tags": [ "Federation" ], "description": "Server-Sent Events stream for federation events. Token expiry closes the stream with a retry directive. Returns `text/event-stream` content type.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "lastEventId", "required": false, "description": "Resume from this event ID (maps to Last-Event-ID header)" } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "SSE event stream (text/event-stream). Events include state-transitions, settlement signals, and gateway revocations.", "content": { "application/json": { "schema": { "description": "SSE event stream (text/event-stream). Events include state-transitions, settlement signals, and gateway revocations.", "type": "string" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/schemas/{contractType}/publish": { "post": { "operationId": "publishFederationSchema", "summary": "Publish a contract type to the federation schema catalog", "tags": [ "Federation" ], "description": "Publish a local contract type to the Hub schema catalog. If visibility is \"full\", a confirmation token is returned and a second call to /confirm is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "visibility" ], "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "visibility": { "type": "string", "enum": [ "hub-only", "full" ] }, "mandateSchema": { "type": "object", "additionalProperties": true }, "receiptSchema": { "type": "object", "additionalProperties": true }, "rulesConfig": { "type": "object", "additionalProperties": true }, "displayName": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 }, "category": { "type": "string", "maxLength": 50 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "in": "path", "name": "contractType", "required": true } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "published": { "type": "boolean" }, "catalogId": { "type": "string" }, "confirmationRequired": { "type": "boolean" }, "confirmationToken": { "type": "string" }, "expiresIn": { "type": "integer" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/schemas/{contractType}/publish/confirm": { "post": { "operationId": "confirmPublishFederationSchema", "summary": "Confirm schema publication with a confirmation token", "tags": [ "Federation" ], "description": "Complete the two-step publish flow for \"full\" visibility schemas by providing the confirmation token returned from the initial publish call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmationToken", "version" ], "additionalProperties": false, "properties": { "confirmationToken": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "minimum": 1 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "in": "path", "name": "contractType", "required": true } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "published", "catalogId" ], "properties": { "published": { "type": "boolean" }, "catalogId": { "type": "string" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/contract-types": { "get": { "operationId": "listFederationContractTypes", "summary": "List published contract types in the federation catalog", "tags": [ "Federation" ], "description": "Browse the federation schema catalog. For \"hub-only\" visibility entries, schema details (mandateSchema, receiptSchema, rulesConfig) are omitted.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "category", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "hub-only", "full" ] }, "in": "query", "name": "visibility", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "offset", "required": false } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "contractType", "version", "visibility", "publishedAt" ], "properties": { "id": { "type": "string" }, "contractType": { "type": "string" }, "version": { "type": "integer" }, "category": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "hub-only", "full" ] }, "publisherGatewayId": { "type": "string", "nullable": true }, "mandateSchema": { "type": "object", "additionalProperties": true, "nullable": true }, "receiptSchema": { "type": "object", "additionalProperties": true, "nullable": true }, "rulesConfig": { "type": "object", "additionalProperties": true, "nullable": true }, "publishedAt": { "type": "string", "format": "date-time" } } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/contract-types/{contractType}": { "get": { "operationId": "getFederationContractType", "summary": "Get a single contract type from the federation catalog", "tags": [ "Federation" ], "description": "Retrieve a specific published contract type. For \"hub-only\" visibility entries, schema details are omitted.", "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "version", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "in": "path", "name": "contractType", "required": true } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contractType", "version", "visibility", "publishedAt" ], "properties": { "id": { "type": "string" }, "contractType": { "type": "string" }, "version": { "type": "integer" }, "category": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "hub-only", "full" ] }, "publisherGatewayId": { "type": "string", "nullable": true }, "mandateSchema": { "type": "object", "additionalProperties": true, "nullable": true }, "receiptSchema": { "type": "object", "additionalProperties": true, "nullable": true }, "rulesConfig": { "type": "object", "additionalProperties": true, "nullable": true }, "publishedAt": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/mandates/{mandateId}/criteria": { "get": { "operationId": "getMandateCriteria", "summary": "Fetch encrypted criteria for a cross-boundary mandate", "tags": [ "Federation" ], "description": "Performer Gateway fetches the encrypted criteria envelope for a mandate they are assigned to. Only the performer_gateway_id can access this endpoint.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "mandateId", "required": true } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "mandateId", "encryptedCriteria", "criteriaCommitment", "senderEphemeralKey" ], "properties": { "mandateId": { "type": "string" }, "encryptedCriteria": { "type": "string", "description": "Base64-encoded encrypted criteria envelope" }, "criteriaCommitment": { "type": "string" }, "senderEphemeralKey": { "type": "string" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "submitMandateCriteria", "summary": "Submit encrypted criteria for relay to performer", "tags": [ "Federation" ], "description": "Principal Gateway submits encrypted criteria for a cross-boundary mandate. Only the principal_gateway_id can submit criteria.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "encryptedCriteria", "criteriaCommitment", "senderEphemeralKey" ], "additionalProperties": false, "properties": { "encryptedCriteria": { "type": "string", "minLength": 1, "description": "Base64-encoded encrypted criteria envelope" }, "criteriaCommitment": { "type": "string", "minLength": 1 }, "senderEphemeralKey": { "type": "string", "minLength": 1 } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "mandateId", "required": true } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "stored" ], "properties": { "stored": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/state-transitions": { "post": { "operationId": "federationStateTransition", "summary": "Submit a cross-instance state transition", "tags": [ "Federation" ], "description": "Submit a signed mandate state transition from a Gateway to the Hub. The Hub verifies the signature, records the transition, and returns the acknowledged hub state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mandateId", "gatewayId", "state", "contractType", "criteriaHash", "role", "seq", "idempotencyKey", "timestamp", "nonce", "signature" ], "additionalProperties": false, "properties": { "mandateId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "gatewayId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "state": { "type": "string", "minLength": 1 }, "contractType": { "type": "string", "minLength": 1, "maxLength": 50 }, "criteriaHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "role": { "type": "string", "enum": [ "principal", "performer" ] }, "performerGatewayId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "seq": { "type": "integer", "minimum": 1 }, "idempotencyKey": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "timestamp": { "type": "string", "format": "date-time" }, "nonce": { "type": "string", "minLength": 16, "maxLength": 64 }, "signature": { "type": "string", "minLength": 1 }, "hopCount": { "type": "integer", "minimum": 0, "maximum": 2, "description": "Cross-hub hop count for mandate routing. Max 2." } } } } } }, "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ack", "hubState", "subStatus", "hubTimestamp", "hubSignature" ], "properties": { "ack": { "type": "boolean" }, "hubState": { "type": "string" }, "subStatus": { "type": "string" }, "hubTimestamp": { "type": "string", "format": "date-time" }, "hubSignature": { "type": "string" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/signals": { "post": { "operationId": "federationSettlementSignal", "summary": "Relay a settlement signal", "tags": [ "Federation" ], "description": "Relay a SETTLE/HOLD/RELEASE signal from the principal Gateway to the performer Gateway via the Hub.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mandateId", "signal", "outcomeHash", "signalSeq", "validUntil", "performerGatewayId", "timestamp", "nonce", "performerSignature" ], "additionalProperties": false, "properties": { "mandateId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "signal": { "type": "string", "enum": [ "SETTLE", "HOLD", "RELEASE" ] }, "outcome": { "type": "string", "enum": [ "PASS", "FAIL" ], "nullable": true }, "outcomeHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "signalSeq": { "type": "integer", "minimum": 1 }, "validUntil": { "type": "string", "format": "date-time" }, "performerGatewayId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "timestamp": { "type": "string", "format": "date-time" }, "nonce": { "type": "string", "minLength": 16, "maxLength": 64 }, "performerSignature": { "type": "string", "minLength": 1 } } } } } }, "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "relayed", "hubSignature", "hubTimestamp", "targetGatewayId" ], "properties": { "relayed": { "type": "boolean" }, "hubSignature": { "type": "string" }, "hubTimestamp": { "type": "string", "format": "date-time" }, "targetGatewayId": { "type": "string" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/gateways/{id}/rotate-key": { "post": { "operationId": "rotateGatewayKeys", "summary": "Rotate Gateway signing and encryption keys", "tags": [ "Federation" ], "description": "Rotate a Gateway's Ed25519 signing and X25519 encryption keys. Requires dual signatures (old + new key) for proof of possession.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "newSigningPublicKey", "newEncryptionPublicKey", "signatureOldKey", "signatureNewKey", "timestamp", "nonce" ], "additionalProperties": false, "properties": { "newSigningPublicKey": { "type": "string", "minLength": 1 }, "newEncryptionPublicKey": { "type": "string", "minLength": 1 }, "signatureOldKey": { "type": "string", "minLength": 1 }, "signatureNewKey": { "type": "string", "minLength": 1 }, "timestamp": { "type": "string", "format": "date-time" }, "nonce": { "type": "string", "minLength": 16, "maxLength": 64 } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "rotated" ], "properties": { "rotated": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/gateways/{id}/revoke": { "post": { "operationId": "revokeGatewaySelf", "summary": "Self-revoke a Gateway", "tags": [ "Federation" ], "description": "Revoke a Gateway using its revocation secret. No bearer token required — uses the secret established during registration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revocationSecret", "reason" ], "additionalProperties": false, "properties": { "revocationSecret": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "enum": [ "key_compromise", "decommission", "administrative" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "id", "required": true } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked", "revokedAt" ], "properties": { "revoked": { "type": "boolean" }, "revokedAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/registration-tokens": { "post": { "operationId": "createRegistrationToken", "summary": "Create a Gateway registration token", "tags": [ "Federation Admin" ], "description": "Generate a single-use registration token that a Gateway presents during federation registration. Optionally scoped to specific contract types.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "maxLength": 255 }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720 }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "allowedContractTypes": { "type": "array", "items": { "type": "string" }, "maxItems": 50 } } } } } }, "security": [ { "platformAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "expiresAt" ], "properties": { "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/gateways": { "get": { "operationId": "listGateways", "summary": "List registered gateways", "tags": [ "Federation Admin" ], "description": "List all registered Gateway instances with status, heartbeat timestamps, and agent/mandate counts. Filterable by status.", "parameters": [ { "schema": { "type": "string", "enum": [ "active", "suspended", "revoked" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "offset", "required": false } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "gatewayId", "organizationId", "status", "endpointUrl", "registeredAt" ], "properties": { "gatewayId": { "type": "string" }, "organizationId": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "status": { "type": "string" }, "endpointUrl": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "lastHeartbeat": { "type": "string", "format": "date-time", "nullable": true }, "lastAgentCount": { "type": "integer" }, "lastMandateCount": { "type": "integer" }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true }, "revocationReason": { "type": "string", "nullable": true }, "registeredAt": { "type": "string", "format": "date-time" } } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/gateways/{id}/revoke": { "post": { "operationId": "adminRevokeGateway", "summary": "Revoke a gateway registration", "tags": [ "Federation Admin" ], "description": "Administratively revoke a Gateway. The revocation is broadcast to all active Gateways on their next heartbeat.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/gateways/{id}/reset-seq": { "post": { "operationId": "resetGatewaySequence", "summary": "Reset gateway sequence counter (backup/restore recovery)", "tags": [ "Federation Admin" ], "description": "Reset a Gateway's monotonic sequence counter after backup/restore or disaster recovery. Required before the Gateway can resume submitting transitions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newSeq": { "type": "integer", "minimum": 0, "description": "New sequence number (default: 0)" } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "reset" ], "properties": { "reset": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/rotate-hub-key": { "post": { "operationId": "rotateHubKey", "summary": "Rotate the Hub Ed25519 signing keypair", "tags": [ "Federation Admin" ], "description": "Generate a new Ed25519 keypair for the Hub. The new key is stored as \"pending\" with a configurable overlap period (default 24h) before the old key expires.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "overlapHours": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "Hours the old key remains valid alongside the new key" } } } } } }, "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "rotated", "newKeyFingerprint", "newPrivateKey", "newPublicKey", "overlapExpiresAt" ], "properties": { "rotated": { "type": "boolean" }, "newKeyFingerprint": { "type": "string", "description": "Fingerprint of the new public key" }, "newPrivateKey": { "type": "string", "description": "Base64-encoded PKCS#8 DER private key — set as AGLEDGER_FEDERATION_SIGNING_KEY, then activate" }, "newPublicKey": { "type": "string", "description": "Base64-encoded SPKI DER public key" }, "overlapExpiresAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/mandates": { "get": { "operationId": "listFederationMandates", "summary": "List federation mandate state", "tags": [ "Federation Admin" ], "description": "List cross-instance mandate state tracked by the Hub. Filterable by gateway, hub state, and contract type.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "query", "name": "gatewayId", "required": false }, { "schema": { "type": "string", "enum": [ "OFFERED", "ACCEPTED", "ACTIVE", "COMPLETED", "DISPUTED", "TERMINAL" ] }, "in": "query", "name": "hubState", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "contractType", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "offset", "required": false } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "mandateId", "principalGatewayId", "contractType", "hubState", "createdAt", "updatedAt" ], "properties": { "mandateId": { "type": "string", "format": "uuid" }, "principalGatewayId": { "type": "string", "format": "uuid" }, "performerGatewayId": { "type": "string", "format": "uuid", "nullable": true }, "contractType": { "type": "string" }, "criteriaHash": { "type": "string" }, "hubState": { "type": "string" }, "subStatus": { "type": "string", "nullable": true }, "principalState": { "type": "string", "nullable": true }, "performerState": { "type": "string", "nullable": true }, "verificationOutcome": { "type": "string", "nullable": true }, "settlementSignal": { "type": "string", "nullable": true }, "signalSeq": { "type": "integer" }, "signalValidUntil": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/audit-log": { "get": { "operationId": "getFederationAuditLog", "summary": "Query federation audit log", "tags": [ "Federation Admin" ], "description": "Query the hash-chained federation audit log. Filterable by gateway, entry type, and mandate ID.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "query", "name": "gatewayId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "entryType", "required": false }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "query", "name": "mandateId", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "offset", "required": false } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "entryType", "payloadHash", "chainPosition", "alg", "createdAt" ], "properties": { "id": { "type": "string" }, "entryType": { "type": "string" }, "gatewayId": { "type": "string", "format": "uuid", "nullable": true }, "mandateId": { "type": "string", "format": "uuid", "nullable": true }, "payload": { "type": "object", "additionalProperties": true }, "payloadHash": { "type": "string" }, "previousHash": { "type": "string", "nullable": true }, "chainPosition": { "type": "integer" }, "alg": { "type": "string" }, "signature": { "type": "string", "nullable": true }, "signatureAlg": { "type": "string", "nullable": true }, "signingKeyId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/health": { "get": { "operationId": "getFederationHealth", "summary": "Federation health summary", "tags": [ "Federation Admin" ], "description": "Return aggregate federation health: gateway counts by status, mandate counts by hub state, and audit chain length.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "gateways", "mandates", "auditChainLength" ], "properties": { "gateways": { "type": "object", "required": [ "active", "suspended", "revoked" ], "properties": { "active": { "type": "integer" }, "suspended": { "type": "integer" }, "revoked": { "type": "integer" } } }, "mandates": { "type": "object", "additionalProperties": { "type": "integer" } }, "auditChainLength": { "type": "integer" }, "lastAuditEntry": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/outbound-dlq": { "get": { "operationId": "listOutboundDlq", "summary": "List failed federation outbound messages", "tags": [ "Federation Admin" ], "description": "List messages in the outbound dead-letter queue that failed delivery to remote Gateways after all retry attempts.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "jobType", "errorMessage", "attempts", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "jobType": { "type": "string" }, "mandateId": { "type": "string", "format": "uuid", "nullable": true }, "agentId": { "type": "string", "nullable": true }, "payload": { "type": "object", "additionalProperties": true }, "errorMessage": { "type": "string" }, "attempts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/outbound-dlq/{id}/retry": { "post": { "operationId": "retryDlqEntry", "summary": "Retry a failed federation message", "tags": [ "Federation Admin" ], "description": "Re-enqueue a dead-letter queue entry for another delivery attempt to the target Gateway.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "retried" ], "properties": { "retried": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/outbound-dlq/{id}": { "delete": { "operationId": "deleteDlqEntry", "summary": "Discard a failed federation message", "tags": [ "Federation Admin" ], "description": "Permanently discard a dead-letter queue entry without retrying. Use when the message is no longer relevant.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/peer": { "post": { "operationId": "peerHandshake", "summary": "Initiate a Hub-to-Hub peering handshake", "tags": [ "Federation Peering" ], "description": "Register a bilateral peering relationship between two Hubs. The initiating Hub provides its signing key, encryption key, a peering token, and an initial agent directory snapshot.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hubId", "signingPublicKey", "encryptionPublicKey", "peeringToken", "agentDirectory" ], "additionalProperties": false, "properties": { "hubId": { "type": "string", "minLength": 1, "maxLength": 255 }, "signingPublicKey": { "type": "string", "minLength": 1 }, "encryptionPublicKey": { "type": "string", "minLength": 1 }, "peeringToken": { "type": "string", "minLength": 16, "maxLength": 256 }, "agentDirectory": { "type": "array", "items": { "type": "object", "required": [ "agentId", "gatewayId", "contractTypes" ], "properties": { "agentId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "gatewayId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contractTypes": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "displayName": { "type": "string", "maxLength": 255 } } }, "maxItems": 1000 } } } } } }, "security": [ { "federationBearer": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "peered", "peerId", "hubSigningPublicKey", "hubEncryptionPublicKey" ], "properties": { "peered": { "type": "boolean" }, "peerId": { "type": "string" }, "hubSigningPublicKey": { "type": "string" }, "hubEncryptionPublicKey": { "type": "string" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/peers": { "get": { "operationId": "listPeerHubs", "summary": "List peered Hubs", "tags": [ "Federation Admin" ], "description": "List all bilateral Hub peering relationships with status, sync health, and agent directory hash.", "parameters": [ { "schema": { "type": "string", "enum": [ "active", "suspended", "revoked" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "offset", "required": false } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "peerId", "peerHubId", "peerUrl", "status", "createdAt" ], "properties": { "peerId": { "type": "string", "format": "uuid" }, "peerHubId": { "type": "string" }, "peerUrl": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended", "revoked" ] }, "agentDirectoryHash": { "type": "string", "nullable": true }, "lastSyncAt": { "type": "string", "format": "date-time", "nullable": true }, "tokenExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/peers/{hubId}/revoke": { "post": { "operationId": "revokePeerHub", "summary": "Revoke a peered Hub", "tags": [ "Federation Admin" ], "description": "Revoke a bilateral peering relationship. All remote agents from this peer are deleted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "path", "name": "hubId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "boolean" }, "remoteAgentsDeleted": { "type": "integer" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/peer/revocations": { "post": { "operationId": "receivePeerRevocationBroadcast", "summary": "Receive a Gateway revocation broadcast from a peer Hub", "tags": [ "Federation Peering" ], "description": "A peer Hub broadcasts that one of its Gateways has been revoked. Delete any remote agent entries for that Gateway.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gatewayId", "revokedAt", "reason" ], "additionalProperties": false, "properties": { "gatewayId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "revokedAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "acknowledged" ], "properties": { "acknowledged": { "type": "boolean" }, "agentsRemoved": { "type": "integer" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/peer/agent-sync": { "post": { "operationId": "receivePeerAgentDirectorySync", "summary": "Receive an agent directory update from a peer Hub", "tags": [ "Federation Peering" ], "description": "A peer Hub pushes a full or incremental agent directory update. Remote agents are upserted and the directory hash is updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hubId", "agents", "directoryHash" ], "additionalProperties": false, "properties": { "hubId": { "type": "string", "minLength": 1, "maxLength": 255 }, "agents": { "type": "array", "items": { "type": "object", "required": [ "agentId", "gatewayId", "contractTypes" ], "properties": { "agentId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "gatewayId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contractTypes": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "displayName": { "type": "string", "maxLength": 255 } } }, "maxItems": 5000 }, "directoryHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "since": { "type": "string", "format": "date-time", "description": "If present, this is an incremental sync since this timestamp" } } } } } }, "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "synced", "agentsUpserted" ], "properties": { "synced": { "type": "boolean" }, "agentsUpserted": { "type": "integer" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/reputation/contribute": { "post": { "operationId": "contributeReputation", "summary": "Submit a reputation contribution for an agent", "tags": [ "Federation" ], "description": "A Gateway submits aggregate mandate statistics for an agent over an ISO week period. Anti-Sybil: the contributing Gateway must have been registered for at least 30 days.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "contractType", "period", "totalMandates", "totalVerified", "totalPassed" ], "additionalProperties": false, "properties": { "agentId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contractType": { "type": "string", "minLength": 1, "maxLength": 50 }, "period": { "type": "string", "pattern": "^\\d{4}-W\\d{2}$", "description": "ISO week, e.g. 2026-W14" }, "totalMandates": { "type": "integer", "minimum": 0 }, "totalVerified": { "type": "integer", "minimum": 0 }, "totalPassed": { "type": "integer", "minimum": 0 }, "signature": { "type": "string" } } } } } }, "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "contributed" ], "properties": { "contributed": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/agents/{agentId}/reputation": { "get": { "operationId": "getAgentReputation", "summary": "Query reputation scores for an agent", "tags": [ "Federation" ], "description": "Returns composite reputation scores for an agent across contract types. Optionally filter by a specific contract type.", "parameters": [ { "schema": { "type": "string", "maxLength": 50 }, "in": "query", "name": "contractType", "required": false }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "agentId", "required": true } ], "security": [ { "federationBearer": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "scores" ], "properties": { "agentId": { "type": "string" }, "scores": { "type": "array", "items": { "type": "object", "required": [ "contractType", "reliability", "accuracy", "efficiency", "compositeScore", "confidence", "sampleSize" ], "properties": { "contractType": { "type": "string" }, "reliability": { "type": "number" }, "accuracy": { "type": "number" }, "efficiency": { "type": "number" }, "compositeScore": { "type": "number" }, "confidence": { "type": "number" }, "sampleSize": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/hub-keys": { "get": { "operationId": "listHubKeys", "summary": "List Hub signing keys", "tags": [ "Federation Admin" ], "description": "List all Hub signing keys with their status (active, pending, expired). Platform auth required.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "publicKey", "keyFingerprint", "status" ], "properties": { "id": { "type": "string" }, "publicKey": { "type": "string" }, "keyFingerprint": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "pending", "expired" ] }, "activatedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/hub-keys/{id}/activate": { "post": { "operationId": "activateHubKey", "summary": "Activate a pending Hub signing key", "tags": [ "Federation Admin" ], "description": "Activate a pending Hub signing key. Only keys with status \"pending\" can be activated.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "activated" ], "properties": { "activated": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/hub-keys/{id}/expire": { "post": { "operationId": "expireHubKey", "summary": "Expire an old Hub signing key", "tags": [ "Federation Admin" ], "description": "Expire a Hub signing key by ID. Sets the key status to \"expired\".", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "expired" ], "properties": { "expired": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/schemas/{contractType}/{version}": { "delete": { "operationId": "deleteSchemaCatalogEntry", "summary": "Delete a schema catalog entry", "tags": [ "Federation Admin" ], "description": "Delete a published contract type from the federation schema catalog by contract type and version. Platform auth required.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "in": "path", "name": "contractType", "required": true }, { "schema": { "type": "integer", "minimum": 1 }, "in": "path", "name": "version", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/peering-tokens": { "post": { "operationId": "generatePeeringToken", "summary": "Generate a peering token for Hub-to-Hub handshake", "tags": [ "Federation Admin" ], "description": "Generate a random peering token for out-of-band sharing with a peer Hub. The admin shares this token with the peer Hub operator, who uses it in the peering handshake.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "maxLength": 255, "description": "Optional label identifying the intended peer" } } } } } }, "security": [ { "platformAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "peeringToken", "createdAt" ], "properties": { "peeringToken": { "type": "string", "description": "Raw peering token — share out-of-band with the peer Hub operator" }, "label": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/peers/{hubId}": { "get": { "operationId": "getPeerDetail", "summary": "Get a single peer Hub detail", "tags": [ "Federation Admin" ], "description": "Get detailed information about a specific peered Hub by its Hub ID.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "path", "name": "hubId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Peer Hub detail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "peerId", "peerHubId", "peerUrl", "status", "createdAt" ], "properties": { "peerId": { "type": "string", "format": "uuid" }, "peerHubId": { "type": "string" }, "peerUrl": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended", "revoked" ] }, "agentDirectoryHash": { "type": "string", "nullable": true }, "lastSyncAt": { "type": "string", "format": "date-time", "nullable": true }, "tokenExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "description": "Peer Hub detail." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/peers/{hubId}/resync": { "post": { "operationId": "resyncPeer", "summary": "Force resync with a peer Hub", "tags": [ "Federation Admin" ], "description": "Reset a peer's sync state (last_sync_at = NULL, agent_directory_hash = NULL) to trigger a full resync on the next cycle.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "path", "name": "hubId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "resyncScheduled" ], "properties": { "resyncScheduled": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/reputation/{agentId}": { "get": { "operationId": "listReputationContributions", "summary": "List all reputation contributions for an agent", "tags": [ "Federation Admin" ], "description": "Returns all raw reputation contributions for an agent across all contract types and periods. Platform auth required.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "agentId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "agentId", "gatewayId", "contractType", "period", "totalMandates", "totalVerified", "totalPassed" ], "properties": { "agentId": { "type": "string", "format": "uuid" }, "gatewayId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "period": { "type": "string" }, "totalMandates": { "type": "integer" }, "totalVerified": { "type": "integer" }, "totalPassed": { "type": "integer" }, "signature": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "resetReputation", "summary": "Reset all reputation data for an agent", "tags": [ "Federation Admin" ], "description": "Delete all reputation contributions and computed scores for an agent. Platform auth required.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "agentId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "contributionsDeleted", "scoresDeleted" ], "properties": { "contributionsDeleted": { "type": "integer" }, "scoresDeleted": { "type": "integer" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/federation/v1/admin/mandates/{mandateId}/criteria-status": { "get": { "operationId": "adminMandateCriteriaStatus", "summary": "Inspect criteria status for a federation mandate", "tags": [ "Federation Admin" ], "description": "Returns whether criteria are present, the commitment hash, and the ephemeral key — but NOT the encrypted criteria itself. Platform auth required.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "mandateId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "mandateId", "hasCriteria", "criteriaCommitment", "senderEphemeralKey" ], "properties": { "mandateId": { "type": "string" }, "hasCriteria": { "type": "boolean" }, "criteriaCommitment": { "type": "string", "nullable": true }, "senderEphemeralKey": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates": { "post": { "operationId": "createMandate", "summary": "Create a new mandate in CREATED status", "tags": [ "Mandates" ], "description": "Creates a mandate in CREATED status. The mandate must be activated (transition to ACTIVE) before receipts can be submitted against it. Enterprise users can only create mandates for their own enterpriseId. The criteria object must conform to the JSON Schema for the specified contract type (use GET /schemas/:contractType to inspect). Supports idempotency via the `Idempotency-Key` header.\n\n**Auth:** enterprise, agent, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contractType", "criteria" ], "properties": { "enterpriseId": { "type": "string", "format": "uuid", "description": "Enterprise that owns this mandate. Optional for enterprise callers (defaults to authenticated enterprise). Required for platform callers." }, "contractType": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Contract type identifier (e.g., ACH-PROC-v1). Use GET /schemas to list available types." }, "contractVersion": { "type": "string", "minLength": 1, "maxLength": 10, "description": "Schema version for the contract type. Defaults to the latest active version." }, "platform": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Payment platform label (e.g., stripe-acp, google-ap2). Defaults to \"generic\"." }, "platformRef": { "type": "string", "maxLength": 255, "description": "External reference ID on the payment platform" }, "projectRef": { "type": "string", "maxLength": 255, "description": "External project reference for grouping related mandates" }, "externalTaskId": { "type": "string", "maxLength": 255, "description": "External task system ID (e.g., CI pipeline run, RPA task ID, workflow step)" }, "criteria": { "type": "object", "maxProperties": 100, "description": "Acceptance criteria per the contract type schema" }, "tolerance": { "type": "object", "properties": { "quantityPct": { "type": "number", "minimum": 0 }, "priceMargin": { "type": "number", "minimum": 0 }, "priceMarginPct": { "type": "number", "minimum": 0 }, "graceSeconds": { "type": "integer", "minimum": 0 }, "budgetMargin": { "type": "number", "minimum": 0 } }, "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Tolerance bands for semantic verification" }, "deadline": { "type": "string", "format": "date-time", "description": "ISO 8601 deadline; mandate auto-expires after this time" }, "agentId": { "type": "string", "format": "uuid", "description": "Agent assigned to fulfill this mandate (optional at creation). Alias: performerAgentId" }, "performerAgentId": { "type": "string", "format": "uuid", "description": "Alias for agentId — agent assigned to fulfill this mandate" }, "parentMandateId": { "type": "string", "format": "uuid", "description": "Parent mandate ID for building delegation chains" }, "commissionPct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Commission percentage for the performer (0-100)" }, "operatingMode": { "type": "string", "enum": [ "cleartext", "encrypted" ], "default": "cleartext", "description": "Operating mode: cleartext (full server verification) or encrypted (self-verification via POST /outcome). Encrypted mode requires verificationMode principal or gated." }, "verificationMode": { "type": "string", "enum": [ "auto", "principal", "gated" ], "default": "auto", "description": "Verification mode: auto (rules engine auto-settles), principal (hold for principal verdict via POST /outcome), gated (run hard rules, then hold for principal verdict)" }, "riskClassification": { "type": "string", "enum": [ "high", "limited", "minimal", "unclassified" ], "default": "unclassified", "description": "EU AI Act risk classification" }, "euAiActDomain": { "type": "string", "enum": [ "biometrics", "critical_infrastructure", "education", "employment", "essential_services", "law_enforcement", "migration", "justice" ], "description": "EU AI Act high-risk domain (only when riskClassification=high)" }, "humanOversight": { "type": "object", "description": "Human oversight designation per EU AI Act Art. 14", "properties": { "overseerName": { "type": "string", "maxLength": 500 }, "overseerRole": { "type": "string", "maxLength": 500 }, "overseerContact": { "type": "string", "maxLength": 500 }, "authorityScope": { "type": "string", "maxLength": 2000 }, "designatedAt": { "type": "string", "format": "date-time" } }, "required": [ "overseerName", "overseerRole", "authorityScope", "designatedAt" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": true, "maxProperties": 50, "description": "Arbitrary key-value data for customer use (max 10KB)" }, "maxSubmissions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of receipt submissions allowed (default: unlimited). When reached, no further revisions can be requested." }, "constraintInheritance": { "type": "string", "enum": [ "none", "advisory", "enforced" ], "default": "none", "description": "Constraint inheritance mode for delegation chains. none: no inheritance (default). advisory: allow but audit when child exceeds parent bounds. enforced: block child creation if exceeds parent." }, "enforcementOverrides": { "type": "object", "properties": { "toleranceEnforcement": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "deadlineEnforcement": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "schemaValidation": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "maxSubmissionsMode": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "expressionRuleMode": { "type": "string", "enum": [ "none", "advisory", "enforced" ] } }, "additionalProperties": false, "description": "Per-mandate enforcement overrides. Can only relax enterprise settings (not tighten). Requires enterprise allowMandateOverrides=true." }, "projectId": { "type": "string", "format": "uuid", "description": "Associate this mandate with a project" }, "dependsOn": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "description": "Informational dependency references to other mandate IDs (no activation gating)" }, "autoActivate": { "type": "boolean", "default": false, "description": "When true, the mandate is created and immediately activated (CREATED → ACTIVE) in a single request. The audit trail records all internal transitions. Default: false." }, "references": { "type": "array", "items": { "type": "object", "required": [ "system", "refType", "refId" ], "properties": { "system": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$", "description": "External system identifier (lowercase, alphanumeric + dots/hyphens/underscores)" }, "refType": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$", "description": "Reference type within the system (e.g., sales-order, ticket, service-principal)" }, "refId": { "type": "string", "minLength": 1, "maxLength": 500, "description": "External identifier within the system" }, "displayName": { "type": "string", "maxLength": 500, "description": "Human-readable label (snapshot at attachment time, not refreshed)" }, "uri": { "type": "string", "maxLength": 2048, "pattern": "^https?://", "description": "URL back to the source system (https only)" }, "attributes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Flat key-value metadata (max 10 keys, max 4KB total)" } }, "additionalProperties": false }, "maxItems": 25, "description": "External entity references to attach at creation (append-only, max 25 per mandate)" } }, "additionalProperties": false }, "example": { "enterpriseId": "550e8400-e29b-41d4-a716-446655440000", "contractType": "ACH-PROC-v1", "contractVersion": "1", "platform": "stripe-acp", "platformRef": "pi_3abc123", "criteria": { "item_description": "Organic whole milk, 1 gallon", "quantity": { "target": 500, "tolerance_pct": 5 }, "price_ceiling": { "amount": 2250, "currency": "USD" }, "supplier_requirements": { "min_rating": 85 } }, "tolerance": { "quantityPct": 5, "priceMargin": 50, "graceSeconds": 86400 }, "deadline": "2026-03-15T00:00:00Z" } } } }, "responses": { "201": { "description": "Mandate created in CREATED status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Invalid request body, unknown contract type, or criteria do not match the contract type schema. When schema validation fails, use examplePayload as a starting point, or inspect requiredFields/optionalFields for valid field names.", "content": { "application/json": { "schema": { "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 'contractType'?\")" }, "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 (eval, enterprise, federation)" }, "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": "Agent-friendly guidance pointing to the schema endpoint for this contract type" }, "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required field names for the criteria object per the contract type schema" }, "optionalFields": { "type": "array", "items": { "type": "string" }, "description": "Optional field names for the criteria object per the contract type schema" }, "examplePayload": { "type": "object", "additionalProperties": true, "description": "A minimal valid request body that an agent can copy and modify. Contains example criteria for the contract type." }, "schemaUrl": { "type": "string", "description": "URL to the contract type schema (e.g., /v1/schemas/ACH-PROC-v1). Call this endpoint to discover required criteria fields." }, "contractType": { "type": "string", "description": "The contract type that was validated against (e.g., ACH-PROC-v1)" }, "currentState": { "type": "string", "description": "Current state of the resource" }, "attemptedTransition": { "type": "string", "description": "Transition that was attempted" }, "validTransitions": { "type": "array", "items": { "type": "string" }, "description": "Valid transitions from the current state" }, "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", "properties": { "keyword": { "type": "string" }, "message": { "type": "string" }, "instancePath": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "description": "Per-field JSON Schema validation errors (present when criteria do not match the contract type schema)" } }, "additionalProperties": false, "description": "Invalid request body, unknown contract type, or criteria do not match the contract type schema. When schema validation fails, use examplePayload as a starting point, or inspect requiredFields/optionalFields for valid field names." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listMandates", "summary": "List mandates for an enterprise", "tags": [ "Mandates" ], "description": "Returns a simple paginated list of mandates for the given enterprise. Enterprise users can only list their own mandates. For advanced filtering, use GET /mandates/search.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false }, { "schema": { "type": "string", "enum": [ "CREATED", "PROPOSED", "ACTIVE", "PROCESSING", "REVISION_REQUESTED", "FULFILLED", "FAILED", "REMEDIATED", "EXPIRED", "CANCELLED", "REJECTED" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by mandate status" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Filter mandates created on or after this timestamp (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "Filter mandates created on or before this timestamp (ISO 8601)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for cursor-based pagination (overrides offset when provided). Returned as nextCursor in previous response." } ], "responses": { "200": { "description": "Wrapped array of mandates.", "content": { "application/json": { "schema": { "description": "Wrapped array of mandates.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mandate" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}": { "get": { "operationId": "getMandate", "summary": "Get mandate by ID", "tags": [ "Mandates" ], "description": "Retrieves a single mandate by its UUID. Enterprise users can only view their own mandates; agents can only view mandates where they are the assigned agent.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateMandate", "summary": "Update mandate fields (CREATED only)", "tags": [ "Mandates" ], "description": "Updates criteria, tolerance, or deadline on a mandate. Only mandates in CREATED status can be updated. At least one field must be provided. The mandate owner is verified before update.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "criteria": { "type": "object", "maxProperties": 100, "description": "Updated acceptance criteria" }, "tolerance": { "type": "object", "properties": { "quantityPct": { "type": "number", "minimum": 0 }, "priceMargin": { "type": "number", "minimum": 0 }, "priceMarginPct": { "type": "number", "minimum": 0 }, "graceSeconds": { "type": "integer", "minimum": 0 }, "budgetMargin": { "type": "number", "minimum": 0 } }, "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Updated tolerance bands" }, "deadline": { "type": "string", "format": "date-time", "description": "Updated deadline" }, "riskClassification": { "type": "string", "enum": [ "high", "limited", "minimal", "unclassified" ], "description": "EU AI Act risk classification" }, "euAiActDomain": { "type": "string", "enum": [ "biometrics", "critical_infrastructure", "education", "employment", "essential_services", "law_enforcement", "migration", "justice" ], "description": "EU AI Act high-risk domain (only when riskClassification=high)" }, "humanOversight": { "type": "object", "description": "Human oversight designation per EU AI Act Art. 14", "properties": { "overseerName": { "type": "string", "maxLength": 500 }, "overseerRole": { "type": "string", "maxLength": 500 }, "overseerContact": { "type": "string", "maxLength": 500 }, "authorityScope": { "type": "string", "maxLength": 2000 }, "designatedAt": { "type": "string", "format": "date-time" } }, "required": [ "overseerName", "overseerRole", "authorityScope", "designatedAt" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": true, "maxProperties": 50, "description": "Arbitrary key-value data for customer use (max 10KB)" } }, "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Invalid update payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/search": { "get": { "operationId": "searchMandates", "summary": "Search mandates with filters and pagination", "tags": [ "Mandates" ], "description": "Enhanced mandate listing with filtering by status, contract type, agent, and date range. Returns paginated results with total count. Enterprise users can only search their own mandates. Supports both offset-based and cursor-based pagination. When `cursor` is provided, it takes precedence over `offset`.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false }, { "schema": { "type": "string", "enum": [ "CREATED", "PROPOSED", "ACTIVE", "PROCESSING", "REVISION_REQUESTED", "FULFILLED", "FAILED", "REMEDIATED", "EXPIRED", "CANCELLED", "REJECTED" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by mandate status" }, { "schema": { "type": "string", "maxLength": 50 }, "in": "query", "name": "contractType", "required": false, "description": "Filter by contract type (e.g., ACH-PROC-v1)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "agentId", "required": false, "description": "Filter by assigned agent" }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "projectRef", "required": false, "description": "Filter by project reference" }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "externalTaskId", "required": false, "description": "Filter by external task ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "parentMandateId", "required": false, "description": "Filter by parent mandate (delegation chain)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Start of date range (inclusive)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "End of date range (inclusive)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "updatedAfter", "required": false, "description": "Filter by updated_at >= this value" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "updatedBefore", "required": false, "description": "Filter by updated_at <= this value" }, { "schema": { "type": "string", "enum": [ "auto", "principal", "gated" ] }, "in": "query", "name": "verificationMode", "required": false, "description": "Filter by verification mode" }, { "schema": { "type": "string", "enum": [ "cleartext", "encrypted" ] }, "in": "query", "name": "operatingMode", "required": false, "description": "Filter by operating mode" }, { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "maxProperties": 5 }, "in": "query", "name": "metadata", "required": false, "description": "Filter by metadata key-value pairs using bracket notation: metadata[key]=value" }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "ref.system", "required": false, "description": "Filter mandates by reference system" }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "ref.type", "required": false, "description": "Filter mandates by reference type" }, { "schema": { "type": "string", "maxLength": 500 }, "in": "query", "name": "ref.id", "required": false, "description": "Filter mandates by reference ID" }, { "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" }, "in": "query", "name": "sort", "required": false, "description": "Sort field" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "order", "required": false, "description": "Sort order" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for cursor-based pagination (overrides offset when provided). Returned as nextCursor in previous response." } ], "responses": { "200": { "description": "Paginated mandate results with total count.", "content": { "application/json": { "schema": { "description": "Paginated mandate results with total count.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mandate" } }, "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" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/summary": { "get": { "operationId": "getMandateSummary", "summary": "Mandate counts by status", "tags": [ "Mandates" ], "description": "Returns a count of mandates grouped by status for the authenticated enterprise. Eliminates the need to call search once per status.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" } ], "responses": { "200": { "description": "Mandate counts grouped by status.", "content": { "application/json": { "schema": { "description": "Mandate counts grouped by status.", "type": "object", "properties": { "countsByStatus": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Mandate count per status (e.g., {\"ACTIVE\": 5, \"FULFILLED\": 12})" }, "total": { "type": "integer", "description": "Total mandates" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/batch": { "post": { "operationId": "batchGetMandates", "summary": "Get multiple mandates by ID", "tags": [ "Mandates" ], "description": "Returns up to 100 mandates by their IDs in a single request. Results are returned in request order. IDs that are not found or not accessible to the caller are silently omitted.\n\n**Auth:** enterprise, agent, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Mandate IDs to fetch (max 100)" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Mandates in request order (missing/inaccessible IDs are omitted).", "content": { "application/json": { "schema": { "description": "Mandates in request order (missing/inaccessible IDs are omitted).", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mandate" } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/transition": { "post": { "operationId": "transitionMandate", "summary": "Transition mandate state", "tags": [ "Mandates" ], "description": "Advances the mandate through its lifecycle state machine. Valid transitions:\n\n- **register**: Locks criteria (mandate remains in CREATED state, ready for activation)\n- **activate**: CREATED -> ACTIVE (open for receipt submissions)\n- **settle**: ACTIVE -> FULFILLED (all obligations met)\n- **refund**: ACTIVE -> REMEDIATED (obligations not met, remediation issued)\n- **cancel**: CREATED/ACTIVE -> CANCELLED\n\nInvalid transitions return 422. Supports idempotency via the `Idempotency-Key` header. Rate limited to 20 requests per minute.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "register", "activate", "settle", "refund", "cancel" ], "description": "State transition action to perform" }, "reason": { "type": "string", "maxLength": 2000, "description": "Optional reason for this transition (recorded in audit vault)" } }, "additionalProperties": false }, "examples": { "example1": { "value": { "action": "register" } }, "example2": { "value": { "action": "activate" } }, "example3": { "value": { "action": "cancel", "reason": "Budget reallocated to higher-priority task" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate after transition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid state transition (e.g., ACTIVE -> CREATED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/bulk": { "post": { "operationId": "bulkCreateMandates", "summary": "Create multiple mandates in a single request", "tags": [ "Mandates" ], "description": "Creates up to 100 mandates in a single request. Each mandate is created independently using database savepoints, so individual failures do not abort the entire batch. Returns HTTP 207 Multi-Status with per-item results.\n\n**Auth:** enterprise, agent, platform. Enterprise users can only bulk-create for their own enterpriseId.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mandates" ], "properties": { "mandates": { "type": "array", "items": { "type": "object", "required": [ "contractType", "criteria" ], "properties": { "enterpriseId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string", "minLength": 1, "maxLength": 50 }, "contractVersion": { "type": "string", "minLength": 1, "maxLength": 10 }, "platform": { "type": "string", "minLength": 1, "maxLength": 50 }, "platformRef": { "type": "string", "maxLength": 255 }, "projectRef": { "type": "string", "maxLength": 255 }, "externalTaskId": { "type": "string", "maxLength": 255 }, "criteria": { "type": "object", "maxProperties": 100 }, "tolerance": { "type": "object", "properties": { "quantityPct": { "type": "number", "minimum": 0 }, "priceMargin": { "type": "number", "minimum": 0 }, "priceMarginPct": { "type": "number", "minimum": 0 }, "graceSeconds": { "type": "integer", "minimum": 0 }, "budgetMargin": { "type": "number", "minimum": 0 } }, "additionalProperties": { "type": "number", "minimum": 0 } }, "deadline": { "type": "string", "format": "date-time" }, "operatingMode": { "type": "string", "enum": [ "cleartext", "encrypted" ], "default": "cleartext" }, "verificationMode": { "type": "string", "enum": [ "auto", "principal", "gated" ], "default": "auto" }, "riskClassification": { "type": "string", "enum": [ "high", "limited", "minimal", "unclassified" ], "default": "unclassified" }, "euAiActDomain": { "type": "string", "enum": [ "biometrics", "critical_infrastructure", "education", "employment", "essential_services", "law_enforcement", "migration", "justice" ] }, "humanOversight": { "type": "object", "description": "Human oversight designation per EU AI Act Art. 14", "properties": { "overseerName": { "type": "string", "maxLength": 500 }, "overseerRole": { "type": "string", "maxLength": 500 }, "overseerContact": { "type": "string", "maxLength": 500 }, "authorityScope": { "type": "string", "maxLength": 2000 }, "designatedAt": { "type": "string", "format": "date-time" } }, "required": [ "overseerName", "overseerRole", "authorityScope", "designatedAt" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": true, "maxProperties": 50 } }, "additionalProperties": false }, "minItems": 1, "maxItems": 100, "description": "Array of mandate objects to create (max 100)" } }, "additionalProperties": false } } } }, "responses": { "207": { "description": "Multi-status response with per-item results and summary counts.", "content": { "application/json": { "schema": { "description": "Multi-status response with per-item results and summary counts.", "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Zero-based index in the input array" }, "status": { "type": "string", "description": "created or error" }, "data": { "$ref": "#/components/schemas/Mandate" }, "error": { "type": "string", "description": "Error message if creation failed" } }, "additionalProperties": false } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/cancel": { "post": { "operationId": "cancelMandate", "summary": "Cancel a mandate", "tags": [ "Mandates" ], "description": "Convenience endpoint that transitions a mandate to CANCELLED status. Can be called on mandates in CREATED or ACTIVE status. An optional reason can be provided. Supports idempotency via the `Idempotency-Key` header. Rate limited to 20 requests per minute.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 2000, "description": "Optional cancellation reason for audit trail" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate after cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Mandate cannot be cancelled from its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/agent": { "post": { "operationId": "createAgentMandate", "summary": "Create an agent-originated mandate", "tags": [ "Agent-to-Agent" ], "description": "Creates a mandate where an agent is the principal (mandate creator). If performerAgentId is provided without proposalMessage, the mandate starts in CREATED (Tier 1 bilateral). If proposalMessage is provided (or no performerAgentId), the mandate starts in PROPOSED (Tier 2 proposal). For delegation (Tier 3), provide parentMandateId to link to an existing mandate chain.\n\n**Auth:** agent only", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contractType", "criteria" ], "properties": { "principalAgentId": { "type": "string", "format": "uuid", "description": "Agent creating this mandate (auto-filled from auth if omitted)" }, "performerAgentId": { "type": "string", "format": "uuid", "description": "Agent assigned to fulfill the mandate" }, "contractType": { "type": "string", "minLength": 1, "maxLength": 50 }, "contractVersion": { "type": "string", "minLength": 1, "maxLength": 10 }, "platform": { "type": "string", "minLength": 1, "maxLength": 50 }, "platformRef": { "type": "string", "maxLength": 255 }, "criteria": { "type": "object", "maxProperties": 100 }, "tolerance": { "type": "object", "properties": { "quantityPct": { "type": "number", "minimum": 0 }, "priceMargin": { "type": "number", "minimum": 0 }, "priceMarginPct": { "type": "number", "minimum": 0 }, "graceSeconds": { "type": "integer", "minimum": 0 }, "budgetMargin": { "type": "number", "minimum": 0 } }, "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Tolerance bands for semantic verification" }, "deadline": { "type": "string", "format": "date-time" }, "commissionPct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Commission percentage for the performer" }, "parentMandateId": { "type": "string", "format": "uuid", "description": "Parent mandate for delegation chains (Tier 3)" }, "proposalMessage": { "type": "string", "maxLength": 2000, "description": "Message for the proposal (triggers Tier 2 flow)" }, "enterpriseId": { "type": "string", "format": "uuid", "description": "Enterprise ID (inherited from parent chain if omitted)" }, "operatingMode": { "type": "string", "enum": [ "cleartext", "encrypted" ], "default": "cleartext", "description": "Operating mode: cleartext or encrypted (self-verification)" }, "verificationMode": { "type": "string", "enum": [ "auto", "principal", "gated" ], "default": "auto", "description": "Verification mode: auto (auto-settle), principal (hold for verdict), gated (rules then verdict)" }, "riskClassification": { "type": "string", "enum": [ "high", "limited", "minimal", "unclassified" ], "default": "unclassified", "description": "EU AI Act risk classification" }, "euAiActDomain": { "type": "string", "enum": [ "biometrics", "critical_infrastructure", "education", "employment", "essential_services", "law_enforcement", "migration", "justice" ], "description": "EU AI Act high-risk domain" }, "humanOversight": { "type": "object", "additionalProperties": true, "description": "Human oversight designation per EU AI Act Art. 14" }, "projectRef": { "type": "string", "maxLength": 255, "description": "Optional project grouping reference" }, "externalTaskId": { "type": "string", "maxLength": 255, "description": "External task system ID (e.g., CI pipeline run, RPA task ID, workflow step)" }, "metadata": { "type": "object", "additionalProperties": true, "maxProperties": 50, "description": "Arbitrary key-value data for customer use (max 10KB)" }, "projectId": { "type": "string", "format": "uuid", "description": "Associate this mandate with a project" }, "dependsOn": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "description": "Informational dependency references to other mandate IDs (no activation gating)" }, "maxSubmissions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of receipt submissions allowed (default: unlimited)" }, "constraintInheritance": { "type": "string", "enum": [ "none", "advisory", "enforced" ], "default": "none", "description": "Constraint inheritance mode for delegation chains. none: no inheritance (default). advisory: allow but audit when child exceeds parent bounds. enforced: block child creation if exceeds parent." }, "enforcementOverrides": { "type": "object", "properties": { "toleranceEnforcement": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "deadlineEnforcement": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "schemaValidation": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "maxSubmissionsMode": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "expressionRuleMode": { "type": "string", "enum": [ "none", "advisory", "enforced" ] } }, "additionalProperties": false, "description": "Per-mandate enforcement overrides. Can only relax enterprise settings (not tighten). Requires enterprise allowMandateOverrides=true." }, "autoActivate": { "type": "boolean", "default": false, "description": "When true, the mandate is created and immediately activated (CREATED → ACTIVE) in a single request. The audit trail records all internal transitions. Default: false." }, "references": { "type": "array", "items": { "type": "object", "required": [ "system", "refType", "refId" ], "properties": { "system": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$", "description": "External system identifier (lowercase, alphanumeric + dots/hyphens/underscores)" }, "refType": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$", "description": "Reference type within the system (e.g., sales-order, ticket, service-principal)" }, "refId": { "type": "string", "minLength": 1, "maxLength": 500, "description": "External identifier within the system" }, "displayName": { "type": "string", "maxLength": 500, "description": "Human-readable label (snapshot at attachment time, not refreshed)" }, "uri": { "type": "string", "maxLength": 2048, "pattern": "^https?://", "description": "URL back to the source system (https only)" }, "attributes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Flat key-value metadata (max 10 keys, max 4KB total)" } }, "additionalProperties": false }, "maxItems": 25, "description": "External entity references to attach at creation (append-only, max 25 per mandate)" } }, "additionalProperties": false }, "example": { "principalAgentId": "550e8400-e29b-41d4-a716-446655440001", "performerAgentId": "550e8400-e29b-41d4-a716-446655440002", "contractType": "ACH-PROC-v1", "contractVersion": "1", "platform": "stripe-acp", "criteria": { "item_description": "Office supplies", "quantity": { "target": 100 }, "price_ceiling": { "amount": 500, "currency": "USD" } }, "commissionPct": 10 } } } }, "responses": { "201": { "description": "Agent mandate created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Validation error (self-assignment, chain depth, schema mismatch, etc.). When schema validation fails, use examplePayload as a starting point, or inspect requiredFields/optionalFields and schemaUrl.", "content": { "application/json": { "schema": { "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 'contractType'?\")" }, "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 (eval, enterprise, federation)" }, "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 mandate/receipt validation (e.g., schema lookup URL)" }, "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required field names for the criteria object per the contract type schema" }, "optionalFields": { "type": "array", "items": { "type": "string" }, "description": "Optional field names for the criteria object per the contract type schema" }, "examplePayload": { "type": "object", "additionalProperties": true, "description": "A minimal valid request body that an agent can copy and modify. Contains example criteria for the contract type." }, "schemaUrl": { "type": "string", "description": "URL to the contract type schema (e.g., /v1/schemas/ACH-PROC-v1). Call this endpoint to discover required criteria fields." }, "contractType": { "type": "string", "description": "The contract type that was validated against (e.g., ACH-PROC-v1)" }, "currentState": { "type": "string", "description": "Current state of the resource" }, "attemptedTransition": { "type": "string", "description": "Transition that was attempted" }, "validTransitions": { "type": "array", "items": { "type": "string" }, "description": "Valid transitions from the current state" }, "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", "properties": { "keyword": { "type": "string" }, "message": { "type": "string" }, "instancePath": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "description": "Per-field JSON Schema validation errors (present when criteria do not match the contract type schema)" } }, "additionalProperties": false, "description": "Validation error (self-assignment, chain depth, schema mismatch, etc.). When schema validation fails, use examplePayload as a starting point, or inspect requiredFields/optionalFields and schemaUrl." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/counter-propose": { "post": { "operationId": "counterProposeMandate", "summary": "Counter-propose a mandate", "tags": [ "Agent-to-Agent" ], "description": "The proposed performer agent counter-proposes modified terms for a mandate. Updates the mandate terms and sets acceptanceStatus to COUNTER_PROPOSED. Include at least one modified field: counterCriteria, counterTolerance, counterDeadline, or counterCommissionPct. The principal agent must then accept the counter via POST /mandates/:id/accept-counter.\n\n**Auth:** agent only (must be the proposed performer)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "counterCriteria": { "type": "object", "maxProperties": 100, "description": "Modified criteria" }, "counterTolerance": { "type": "object", "properties": { "quantityPct": { "type": "number", "minimum": 0 }, "priceMargin": { "type": "number", "minimum": 0 }, "priceMarginPct": { "type": "number", "minimum": 0 }, "graceSeconds": { "type": "integer", "minimum": 0 }, "budgetMargin": { "type": "number", "minimum": 0 } }, "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Modified tolerance" }, "counterDeadline": { "type": "string", "format": "date-time", "description": "Modified deadline" }, "counterCommissionPct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Modified commission" }, "message": { "type": "string", "maxLength": 2000, "description": "Message explaining the counter-proposal" } }, "additionalProperties": false }, "example": { "counterCriteria": { "price_ceiling": { "amount": 600, "currency": "USD" } }, "message": "Need higher budget" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate after counter-proposal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Invalid counter-proposal (wrong state, no modified fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/accept": { "post": { "operationId": "acceptMandate", "summary": "Accept a mandate proposal", "tags": [ "Agent-to-Agent" ], "description": "The proposed performer agent accepts a mandate. Transitions the mandate to CREATED with ACCEPTED status.\n\n**Auth:** agent only (must be the proposed performer)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 2000, "description": "Optional message explaining the acceptance" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate after acceptance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Invalid state for acceptance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/reject": { "post": { "operationId": "rejectMandate", "summary": "Reject a mandate proposal", "tags": [ "Agent-to-Agent" ], "description": "The proposed performer agent rejects a mandate. Transitions the mandate to REJECTED (terminal).\n\n**Auth:** agent only (must be the proposed performer)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 2000, "description": "Optional message explaining the rejection" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate after rejection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Invalid state for rejection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/accept-counter": { "post": { "operationId": "acceptCounterProposal", "summary": "Accept a counter-proposal", "tags": [ "Agent-to-Agent" ], "description": "The principal agent accepts a counter-proposal from the performer. Transitions the mandate to CREATED with ACCEPTED status.\n\n**Auth:** agent only (must be the principal agent)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate after accepting counter-proposal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "No counter-proposal to accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/agent/principal": { "get": { "operationId": "listAgentPrincipalMandates", "summary": "List mandates where agent is principal", "tags": [ "Agent-to-Agent" ], "description": "Returns mandates created by the authenticated agent (where they are the hiring party).\n\n**Auth:** agent only", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for cursor-based pagination (overrides offset when provided). Returned as nextCursor in previous response." } ], "responses": { "200": { "description": "Wrapped array of mandates.", "content": { "application/json": { "schema": { "description": "Wrapped array of mandates.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mandate" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/agent/proposals": { "get": { "operationId": "listAgentProposals", "summary": "List proposals awaiting agent response", "tags": [ "Agent-to-Agent" ], "description": "Returns mandates proposed to the authenticated agent that are awaiting acceptance.\n\n**Auth:** agent only", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for cursor-based pagination (overrides offset when provided). Returned as nextCursor in previous response." } ], "responses": { "200": { "description": "Wrapped array of proposed mandates.", "content": { "application/json": { "schema": { "description": "Wrapped array of proposed mandates.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mandate" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/chain": { "get": { "operationId": "getMandateChain", "summary": "Get full delegation chain", "tags": [ "Agent-to-Agent" ], "description": "Returns all mandates in a delegation chain, ordered by depth. Access: enterprise owner of root, any agent in chain, or platform.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Wrapped array of mandates in the chain.", "content": { "application/json": { "schema": { "description": "Wrapped array of mandates in the chain.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mandate" } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/sub-mandates": { "get": { "operationId": "getSubMandates", "summary": "Get direct sub-mandates", "tags": [ "Agent-to-Agent" ], "description": "Returns the immediate child mandates of a given mandate in a delegation chain.\n\n**Auth:** enterprise, agent, platform (must have access to the parent mandate)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Wrapped array of sub-mandates.", "content": { "application/json": { "schema": { "description": "Wrapped array of sub-mandates.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mandate" } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/revision": { "post": { "operationId": "requestRevision", "summary": "Request revision after principal rejection", "tags": [ "Mandates" ], "description": "Transitions a mandate from FAILED to REVISION_REQUESTED, allowing the performer to submit a new receipt. Only the principal (enterprise owner or delegating agent) can request revision. Enforces max_submissions cap — if the cap is reached, revision is blocked.\n\n**Auth:** enterprise, agent, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 2000, "description": "Reason for requesting revision (recorded in audit trail)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate transitioned to REVISION_REQUESTED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "Invalid state or max submissions reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/receipts": { "post": { "operationId": "submitReceipt", "summary": "Submit task attestation evidence", "tags": [ "Receipts" ], "description": "Submits receipt evidence against an active mandate. Phase 1 structural validation (JSON Schema conformance) runs synchronously. If the evidence does not conform to the contract type receipt schema, the request is rejected with HTTP 400 including `validationErrors` (per-field details) and `schemaUrl` (link to the expected schema). The mandate stays in its current state — no receipt is recorded and no state transition occurs.\n\nIf Phase 1 passes (HTTP 201), Phase 2 semantic verification (field-by-field checks with tolerance bands) is triggered asynchronously via pg-boss; results are delivered via webhook.\n\nUse `GET /v1/schemas/{contractType}` to discover the expected evidence structure before submitting.\n\nThe mandate must be in ACTIVE or REVISION_REQUESTED status. The requester must have access to the parent mandate. Duplicate submissions with the same idempotencyKey return the original receipt (HTTP 200 instead of 201).\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evidence" ], "properties": { "evidence": { "type": "object", "maxProperties": 100, "description": "Evidence payload matching the contract type receipt schema" }, "evidenceHash": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$", "description": "Client-provided SHA-256 hash (required for encrypted mode; server cannot compute it)" }, "idempotencyKey": { "type": "string", "maxLength": 255, "description": "Client-side idempotency key for deduplication" } }, "additionalProperties": false }, "example": { "evidence": { "item_description": "Organic whole milk, 1 gallon", "quantity": 495, "unit_price": { "amount": 4.29, "currency": "USD" }, "total_cost": { "amount": 2123.55, "currency": "USD" }, "supplier": { "id": "SUP-001", "name": "Pacific Dairy Co.", "rating": 92 }, "confirmation_ref": "ORD-2026-03-001" }, "idempotencyKey": "receipt-2026-03-001" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "200": { "description": "Idempotent return -- receipt with this idempotencyKey already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "201": { "description": "Receipt created — evidence passed structural validation. Phase 2 semantic verification triggered asynchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Receipt evidence does not conform to the contract type schema. Inspect validationErrors for details and schemaUrl for the expected structure. The mandate remains in its current state — fix the evidence and retry.", "content": { "application/json": { "schema": { "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 'contractType'?\")" }, "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 (eval, enterprise, federation)" }, "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 mandate/receipt validation (e.g., schema lookup URL)" }, "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required fields for the request body (present on 400 for mandate/receipt creation)" }, "optionalFields": { "type": "array", "items": { "type": "string" }, "description": "Optional fields for the request body (present on 400 for mandate/receipt creation)" }, "examplePayload": { "type": "object", "additionalProperties": true, "description": "Example request body for mandate/receipt creation" }, "schemaUrl": { "type": "string", "description": "URL to the contract type schema for the expected evidence structure (e.g., /v1/schemas/ACH-PROC-v1)" }, "contractType": { "type": "string", "description": "Contract type related to the validation error" }, "currentState": { "type": "string", "description": "Current state of the resource" }, "attemptedTransition": { "type": "string", "description": "Transition that was attempted" }, "validTransitions": { "type": "array", "items": { "type": "string" }, "description": "Valid transitions from the current state" }, "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", "properties": { "keyword": { "type": "string" }, "message": { "type": "string" }, "instancePath": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "description": "JSON Schema validation errors from receipt evidence validation" } }, "additionalProperties": false, "description": "Receipt evidence does not conform to the contract type schema. Inspect validationErrors for details and schemaUrl for the expected structure. The mandate remains in its current state — fix the evidence and retry." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listReceipts", "summary": "List receipts for a mandate", "tags": [ "Receipts" ], "description": "Returns a paginated list of all receipts submitted against the specified mandate. The requester must have access to the parent mandate.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for cursor-based pagination (overrides offset when provided). Returned as nextCursor in previous response." }, { "schema": { "type": "string", "enum": [ "ACCEPTED", "INVALID", "WARNING" ] }, "in": "query", "name": "structuralValidation", "required": false, "description": "Filter by Phase 1 structural validation result" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "200": { "description": "Paginated receipts for the mandate.", "content": { "application/json": { "schema": { "description": "Paginated receipts for the mandate.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Receipt" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/receipts/{receiptId}": { "get": { "operationId": "getReceipt", "summary": "Get receipt by ID", "tags": [ "Receipts" ], "description": "Retrieves a single receipt by ID. The requester must have access to the parent mandate.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "receiptId", "required": true } ], "responses": { "200": { "description": "Receipt details with validation results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate or receipt not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks": { "post": { "operationId": "createWebhook", "summary": "Register a webhook subscription", "tags": [ "Webhooks" ], "description": "Registers a new webhook subscription. The signing secret is generated server-side and returned once in the response -- store it securely for signature verification. The URL is validated against SSRF (blocks RFC 1918, link-local, loopback, and AWS metadata service IPs). Supports idempotency via the `Idempotency-Key` header.\n\n**Recommended events** (cover the full mandate lifecycle):\n`mandate.created` — a mandate now exists (status reflects final state after auto-activate),\n`mandate.receipt_submitted` — an agent submitted a receipt,\n`mandate.verification_complete` — verification finished,\n`mandate.fulfilled` / `mandate.failed` — final outcome,\n`mandate.expired` / `mandate.cancelled` — terminal states.\n\nAlso available: `mandate.settled` (deprecated alias for fulfilled), `mandate.proposed`, `mandate.proposal_accepted`, `mandate.proposal_rejected`, `mandate.delegated`, `mandate.revision_requested`, `signal.emitted`, `dispute.opened`, `dispute.resolved`, `proxy.session.synced`, `proxy.mandate.detected`, `proxy.mandate.formalized`, `federation.mandate.offered`, `federation.mandate.accepted`, `federation.mandate.state_changed`, `federation.settlement.signal`, `federation.gateway.registered`, `federation.gateway.revoked`, `mandate.reference_added`, `agent.reference_added`.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "eventTypes" ], "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "HTTPS endpoint URL to receive webhook deliveries" }, "eventTypes": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "minItems": 1, "maxItems": 50, "description": "Event types to subscribe to. Values are validated against the known set of 28 event types." }, "format": { "type": "string", "enum": [ "standard", "cloudevents" ], "default": "standard", "description": "Payload format: standard (default) or cloudevents (CloudEvents 1.0 envelope with application/cloudevents+json content type)" } }, "additionalProperties": false }, "examples": { "example1": { "value": { "url": "https://api.example.com/webhooks/agledger", "eventTypes": [ "mandate.created", "mandate.receipt_submitted", "mandate.verification_complete", "mandate.fulfilled", "mandate.failed", "mandate.expired", "mandate.cancelled" ] } }, "example2": { "value": { "url": "https://api.example.com/webhooks/signals", "eventTypes": [ "signal.emitted", "mandate.fulfilled", "mandate.failed" ] } } } } } }, "responses": { "201": { "description": "Webhook created. The `secret` field is only returned on creation -- store it securely for HMAC signature verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "400": { "description": "Invalid URL (e.g., SSRF blocked) or invalid event types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listWebhooks", "summary": "List webhook subscriptions", "tags": [ "Webhooks" ], "description": "Returns webhook subscriptions for the authenticated owner. The secret field is NOT included in list responses.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Pagination cursor (opaque, from previous response). Overrides offset when provided." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for offset-based pagination. Ignored when cursor is provided." }, { "schema": { "type": "string", "format": "uri", "maxLength": 2048 }, "in": "query", "name": "url", "required": false, "description": "Filter by exact webhook URL (for provisioning lookups)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}": { "get": { "operationId": "getWebhook", "summary": "Get a webhook subscription by ID", "tags": [ "Webhooks" ], "description": "Returns a single webhook subscription. The secret field is NOT included.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Webhook subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Deactivate a webhook subscription", "tags": [ "Webhooks" ], "description": "Soft-deletes (deactivates) a webhook subscription. The webhook will no longer receive deliveries. Only the owner of the webhook can deactivate it.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "204": { "description": "Webhook deactivated successfully." }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateWebhook", "summary": "Update webhook subscription", "tags": [ "Webhooks" ], "description": "Update the URL and/or event type filters for an existing webhook subscription without regenerating the signing secret. Only the subscription owner can update.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "New HTTPS endpoint URL" }, "eventTypes": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "minItems": 1, "maxItems": 50, "description": "New event type filter" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Webhook updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "400": { "description": "Invalid URL or event types, or webhook is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}/rotate": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate webhook signing secret", "tags": [ "Webhooks" ], "description": "Generates a new HMAC-SHA256 signing secret for the webhook subscription. The new secret is returned once in the response -- store it securely. The old secret is immediately invalidated. Only the webhook owner can rotate.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Secret rotated. The `secret` field contains the new signing secret -- store it securely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "400": { "description": "Webhook is inactive and cannot have its secret rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}/ping": { "post": { "operationId": "pingWebhook", "summary": "Send a test ping to a webhook", "tags": [ "Webhooks" ], "description": "Sends a signed test payload (`webhook.test` event) to the webhook URL and returns the response. Use this to verify your endpoint is reachable and correctly verifying signatures. Only the webhook owner can send pings.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Ping result with HTTP status code, response body (truncated to 1024 chars), and round-trip duration.", "content": { "application/json": { "schema": { "description": "Ping result with HTTP status code, response body (truncated to 1024 chars), and round-trip duration.", "type": "object", "properties": { "statusCode": { "type": "integer", "description": "HTTP status code from the webhook endpoint (0 if connection failed)" }, "body": { "type": "string", "description": "Response body from the endpoint (truncated to 1024 characters)" }, "durationMs": { "type": "integer", "description": "Round-trip duration in milliseconds" }, "success": { "type": "boolean", "description": "Whether the ping received a 2xx response" }, "deliveryId": { "type": "string", "format": "uuid", "description": "Unique delivery ID for this ping" }, "httpStatus": { "type": "integer", "description": "Alias for statusCode — HTTP status code from the webhook endpoint" }, "latencyMs": { "type": "integer", "description": "Alias for durationMs — round-trip duration in milliseconds" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}/deliveries": { "get": { "operationId": "listDeliveries", "summary": "List webhook delivery log", "tags": [ "Webhooks" ], "description": "Returns the delivery log for a specific webhook subscription, ordered by creation time descending. Use this to debug delivery failures and monitor retry status. Only the webhook owner can view deliveries.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Pagination cursor (opaque, from previous response). Overrides offset when provided." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for offset-based pagination. Ignored when cursor is provided." }, { "schema": { "type": "string", "enum": [ "PENDING", "DELIVERED", "FAILED", "DEAD_LETTER" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by delivery status" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}/dlq": { "get": { "operationId": "listWebhookDlq", "summary": "List dead-lettered events for a webhook", "tags": [ "Webhooks" ], "description": "Returns failed webhook deliveries that exhausted all retries. Only the subscription owner can view DLQ entries.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subscriptionId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "eventType": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "errorMessage": { "type": "string" }, "attempts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}/dlq/{dlqId}/retry": { "post": { "operationId": "retryWebhookDlq", "summary": "Retry a specific dead-lettered event", "tags": [ "Webhooks" ], "description": "Removes the entry from the DLQ and re-enqueues it for delivery. Only the subscription owner can retry.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "dlqId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook or DLQ entry not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}/dlq/retry-all": { "post": { "operationId": "retryAllWebhookDlq", "summary": "Retry all dead-lettered events for a webhook", "tags": [ "Webhooks" ], "description": "Removes all DLQ entries for this subscription and re-enqueues them (max 100 per call).\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "retried": { "type": "integer", "description": "Number of entries successfully re-enqueued" }, "failed": { "type": "integer", "description": "Number of entries that failed to re-enqueue" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}/pause": { "post": { "operationId": "pauseWebhook", "summary": "Pause webhook deliveries", "tags": [ "Webhooks" ], "description": "Temporarily suspends delivery for this subscription. The subscription remains active and events arriving during the pause window are dropped (not queued). Resume to restart delivery.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Webhook paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "400": { "description": "Webhook is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{webhookId}/resume": { "post": { "operationId": "resumeWebhook", "summary": "Resume webhook deliveries", "tags": [ "Webhooks" ], "description": "Resumes delivery for a paused subscription.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Webhook resumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "400": { "description": "Webhook is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/events": { "get": { "operationId": "listEvents", "summary": "List events for reconciliation", "tags": [ "Events" ], "description": "Reconciliation endpoint for consumers to catch events that may have been missed by webhooks. Requires a `since` timestamp to bound the query. Enterprise users only see events for their own mandates. Supports filtering by mandate ID and event type. Supports cursor-based pagination.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "since", "required": true, "description": "Return events created after this timestamp (required)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "mandateId", "required": false, "description": "Filter events for a specific mandate" }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "eventType", "required": false, "description": "Filter by event type (e.g., mandate.fulfilled)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for cursor-based pagination (overrides offset when provided). Returned as nextCursor in previous response." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Sort order by created_at (default: asc)" } ], "responses": { "200": { "description": "Paginated events matching the filter criteria.", "content": { "application/json": { "schema": { "description": "Paginated events matching the filter criteria.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventType": { "type": "string", "description": "Event type (e.g., mandate.created, verification.complete, dispute.resolved)" }, "mandateId": { "type": [ "null", "string" ], "format": "uuid" }, "agentId": { "type": [ "null", "string" ], "format": "uuid" }, "payload": { "type": "object", "additionalProperties": true, "description": "Event-specific payload data" }, "createdAt": { "type": "string", "format": "date-time" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/dispute": { "post": { "operationId": "initiateDispute", "summary": "Initiate a dispute with auto Tier 1 re-adjudication", "tags": [ "Disputes" ], "description": "Initiates a dispute against a mandate. Tier 1 automatic re-adjudication runs immediately with expanded tolerance bands. If Tier 1 resolves the dispute, the response includes the auto-resolution result. If unresolved, the dispute remains OPEN for evidence submission and can be escalated to Tier 2 (manual review) and Tier 3 (binding arbitration). Emits `dispute.initiated` event.\n\nSupports idempotency via the `Idempotency-Key` header. Rate limited to 10 requests per minute.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grounds" ], "properties": { "grounds": { "type": "string", "enum": [ "equivalent_item", "fraudulent_receipt", "mandate_ambiguity", "pricing_dispute", "quality_issue", "other" ], "description": "Category of dispute grounds" }, "context": { "type": "string", "maxLength": 2000, "minLength": 1, "description": "Free-text explanation of the dispute" } }, "additionalProperties": false }, "example": { "grounds": "pricing_dispute", "context": "The total price of $2,350 exceeds the mandate ceiling of $2,250 by 4.4%, outside the 3% tolerance band." } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "201": { "description": "Dispute created. If Tier 1 auto-resolved, `tier1Result.autoResolved` is true.", "content": { "application/json": { "schema": { "description": "Dispute created. If Tier 1 auto-resolved, `tier1Result.autoResolved` is true.", "type": "object", "properties": { "dispute": { "$ref": "#/components/schemas/DisputeResponse" }, "tier1Result": { "type": [ "null", "object" ], "properties": { "autoResolved": { "type": "boolean", "description": "Whether Tier 1 automatic re-adjudication resolved the dispute" }, "outcome": { "type": [ "null", "string" ], "description": "Auto-resolution outcome if resolved" } }, "additionalProperties": false }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request body or mandate already has an active dispute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getDispute", "summary": "Get dispute status and evidence history", "tags": [ "Disputes" ], "description": "Retrieves the current dispute for a mandate, including all submitted evidence. The requester must have access to the parent mandate.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "200": { "description": "Dispute details with full evidence history.", "content": { "application/json": { "schema": { "description": "Dispute details with full evidence history.", "type": "object", "properties": { "dispute": { "$ref": "#/components/schemas/DisputeResponse" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/DisputeEvidence" } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate or dispute not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/dispute/evidence": { "post": { "operationId": "submitDisputeEvidence", "summary": "Submit evidence during dispute window", "tags": [ "Disputes" ], "description": "Submits evidence for an active dispute. Evidence can only be submitted while the evidence window is open (check `evidenceWindowClosesAt` on the dispute). Both parties (enterprise and agent) can submit evidence. Supports idempotency via the `Idempotency-Key` header. Rate limited to 10 requests per minute.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evidenceType", "payload" ], "properties": { "evidenceType": { "type": "string", "enum": [ "screenshot", "external_lookup", "document", "communication", "other" ], "description": "Category of evidence being submitted" }, "payload": { "type": "object", "maxProperties": 100, "description": "Evidence data payload" } }, "additionalProperties": false }, "example": { "evidenceType": "document", "payload": { "type": "invoice", "url": "https://storage.example.com/invoices/INV-2026-001.pdf", "description": "Original supplier invoice showing unit price of $4.29" } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "201": { "description": "Evidence submitted and recorded.", "content": { "application/json": { "schema": { "description": "Evidence submitted and recorded.", "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" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "400": { "description": "Evidence window closed or invalid evidence type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate or dispute not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/dispute/escalate": { "post": { "operationId": "escalateDispute", "summary": "Escalate dispute to next tier", "tags": [ "Disputes" ], "description": "Escalates the dispute to the next resolution tier:\n\n- **Tier 1 -> Tier 2** (TIER_2_REVIEW): manual human review\n- **Tier 2 -> Tier 3** (TIER_3_ARBITRATION): binding arbitration with a flat fee\n\nTier 3 is the final tier and cannot be escalated further. Supports idempotency via the `Idempotency-Key` header. Rate limited to 10 requests per minute.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "200": { "description": "Dispute after escalation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeResponse" } } } }, "400": { "description": "Dispute already at maximum tier or not in an escalatable state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate or dispute not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{agentId}/reputation": { "get": { "operationId": "getAgentReputation", "summary": "Get composite reputation scores for all contract types", "tags": [ "Reputation" ], "description": "Returns reputation scores for the specified agent across all contract types they have participated in. Each entry includes reliability, accuracy, and efficiency dimensions plus a confidence level that increases with transaction volume.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Reputation scores, one per contract type.", "content": { "application/json": { "schema": { "description": "Reputation scores, one per contract type.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReputationScore" }, "description": "Array of reputation scores, one per contract type." }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "null", "string" ] } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{agentId}/reputation/{contractType}": { "get": { "operationId": "getAgentReputationByType", "summary": "Get reputation score for a specific contract type", "tags": [ "Reputation" ], "description": "Returns the reputation score for the specified agent and contract type combination. Scores are auto-recalculated when verification.complete and dispute.resolved events occur.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "maxLength": 50 }, "in": "path", "name": "contractType", "required": true } ], "responses": { "200": { "description": "Reputation score for the agent and contract type, with recent history.", "content": { "application/json": { "schema": { "description": "Reputation score for the agent and contract type, with recent history.", "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string", "description": "Contract type this score applies to" }, "reliabilityScore": { "type": [ "null", "number" ], "description": "Task completion reliability (0-100)" }, "accuracyScore": { "type": [ "null", "number" ], "description": "Evidence accuracy vs mandate criteria (0-100)" }, "efficiencyScore": { "type": [ "null", "number" ], "description": "Time-to-completion efficiency (0-100)" }, "compositeScore": { "type": [ "null", "number" ], "description": "Weighted composite of all dimensions (0-100)" }, "confidenceLevel": { "type": [ "null", "number" ], "description": "Statistical confidence (0-1); tightens as transaction volume grows" }, "totalMandates": { "type": "integer", "description": "Total mandates assigned to this agent for this contract type" }, "totalVerified": { "type": "integer", "description": "Number of mandates with completed verification" }, "totalPassed": { "type": "integer", "description": "Number of mandates that passed verification" }, "lastUpdatedAt": { "type": "string", "format": "date-time" }, "formulaVersion": { "type": "integer", "description": "Scoring formula version for reproducibility" }, "recentHistory": { "type": "array", "items": { "type": "object", "properties": { "mandateId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "status": { "type": "string", "description": "Mandate status at time of record" }, "outcome": { "type": "string", "description": "Verification outcome (PASS, FAIL, PENDING)" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "format": "date-time" } }, "additionalProperties": false }, "description": "Recent mandate history entries with verification outcomes (up to 10)" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent or contract type not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{agentId}/history": { "get": { "operationId": "getAgentHistory", "summary": "Get agent transaction history", "tags": [ "Reputation" ], "description": "Returns the paginated transaction history for the specified agent. Agents can only view their own history; enterprise and platform users can view any agent.\n\n**Auth:** enterprise, agent (own history only), platform", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 50 }, "in": "query", "name": "contractType", "required": false, "description": "Filter by contract type (e.g., ACH-PROC-v1)" }, { "schema": { "type": "string", "enum": [ "PASS", "FAIL" ] }, "in": "query", "name": "outcome", "required": false, "description": "Filter by verification outcome" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Filter mandates created on or after this date" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "Filter mandates created on or before this date" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Paginated transaction history for the agent.", "content": { "application/json": { "schema": { "description": "Paginated transaction history for the agent.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "mandateId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "status": { "type": "string", "description": "Mandate status at time of record" }, "outcome": { "type": "string", "description": "Verification outcome (PASS, FAIL, PENDING)" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of history entries" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{agentId}/capabilities": { "get": { "operationId": "getAgentCapabilities", "summary": "Get agent accepted contract types", "tags": [ "Capabilities" ], "description": "Returns the contract types this agent has declared it accepts, enriched with reputation data for each type.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Agent capabilities with reputation enrichment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "contractType": { "type": "string" }, "declaredAt": { "type": "string", "format": "date-time" }, "reputation": { "type": [ "null", "object" ], "properties": { "compositeScore": { "type": [ "null", "number" ] }, "confidenceLevel": { "type": [ "null", "number" ] }, "totalMandates": { "type": "integer" }, "totalPassed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false, "description": "Agent capabilities with reputation enrichment." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "setAgentCapabilities", "summary": "Set agent accepted contract types", "tags": [ "Capabilities" ], "description": "Replace the full set of contract types this agent accepts. Empty array clears all declarations (agent accepts all types).\n\n**Auth:** agent (self only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contractTypes" ], "properties": { "contractTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 100, "description": "Contract types the agent accepts. Empty array clears all declarations." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Updated agent capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "contractType": { "type": "string" }, "declaredAt": { "type": "string", "format": "date-time" }, "reputation": { "type": [ "null", "object" ], "properties": { "compositeScore": { "type": [ "null", "number" ] }, "confidenceLevel": { "type": [ "null", "number" ] }, "totalMandates": { "type": "integer" }, "totalPassed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false, "description": "Updated agent capabilities." } } } }, "400": { "description": "Invalid contract type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dashboard/summary": { "get": { "operationId": "getDashboardSummary", "summary": "Enterprise dashboard summary", "tags": [ "Dashboard" ], "description": "Returns aggregate summary for the authenticated enterprise: total mandates, active, fulfilled, disputed counts, average completion time, and top agents by success rate.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" } ], "responses": { "200": { "description": "Dashboard summary.", "content": { "application/json": { "schema": { "description": "Dashboard summary.", "type": "object", "properties": { "totalMandates": { "type": "integer" }, "activeCount": { "type": "integer" }, "fulfilledCount": { "type": "integer" }, "disputedCount": { "type": "integer" }, "avgCompletionTime": { "type": "number" }, "topAgents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "successRate": { "type": "number" } }, "additionalProperties": false } }, "totalSettlementSignals": { "type": "integer", "description": "Total number of settlement signals (SETTLE + HOLD + RELEASE) emitted for this enterprise" }, "signalBreakdown": { "type": "object", "description": "Settlement signal counts by type", "properties": { "settle": { "type": "integer", "description": "Count of SETTLE signals" }, "hold": { "type": "integer", "description": "Count of HOLD signals" }, "release": { "type": "integer", "description": "Count of RELEASE signals" } }, "additionalProperties": false }, "disputeValue": { "type": "integer", "description": "Total number of disputes filed (proxy for financial risk — mandate monetary amounts are not stored server-side)" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dashboard/metrics": { "get": { "operationId": "getDashboardMetrics", "summary": "Enterprise dashboard time-series metrics", "tags": [ "Dashboard" ], "description": "Returns time-series metrics for mandates, receipts, disputes, and average verification time grouped by daily, weekly, or monthly buckets.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" }, "in": "query", "name": "granularity", "required": false } ], "responses": { "200": { "description": "Time-series metrics.", "content": { "application/json": { "schema": { "description": "Time-series metrics.", "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "mandates": { "type": "integer" }, "receipts": { "type": "integer" }, "disputes": { "type": "integer" }, "avgVerificationTime": { "type": [ "null", "number" ] } }, "additionalProperties": false } }, "granularity": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "The granularity used for the time-series buckets" }, "from": { "type": [ "null", "string" ], "format": "date-time", "description": "Start of the requested date range (null if not specified)" }, "to": { "type": [ "null", "string" ], "format": "date-time", "description": "End of the requested date range (null if not specified)" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dashboard/audit-trail": { "get": { "operationId": "getAuditTrail", "summary": "Get full audit chain for a mandate", "tags": [ "Dashboard" ], "description": "Returns the tamper-evident audit trail for a mandate. Each entry is cryptographically chained: the `payloadHash` of each entry is computed from its payload, and `previousHash` links to the prior entry, forming a hash chain that can be independently verified. The requester must have access to the mandate.\n\n**Auth:** enterprise, agent, platform (must have access to the mandate)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "mandateId", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 }, "in": "query", "name": "limit", "required": false, "description": "Max entries per page" }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "afterPosition", "required": false, "description": "Return entries after this chain position (cursor-style pagination)" }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Number of entries to skip (offset-style pagination). Mutually exclusive with afterPosition." } ], "responses": { "200": { "description": "Paginated audit vault entries forming a hash chain.", "content": { "application/json": { "schema": { "description": "Paginated audit vault entries forming a hash chain.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "entryType": { "type": "string", "description": "Audit entry type (e.g., STATE_CHANGE, RECEIPT_SUBMITTED, VERIFICATION_RESULT)" }, "description": { "type": "string", "description": "Human-readable description of the event" }, "payload": { "type": "object", "additionalProperties": true, "description": "Event-specific data" }, "payloadHash": { "type": "string", "description": "SHA-256 hash of the canonicalized payload" }, "previousHash": { "type": [ "null", "string" ], "description": "Hash of the previous entry in the chain (null for first entry)" }, "chainPosition": { "type": "integer", "description": "Position in the audit chain (0-based)" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "hasMore": { "type": "boolean", "description": "Whether more entries exist beyond this page" }, "nextCursor": { "type": [ "null", "string" ], "description": "Cursor for the next page (chain position of last entry, or null)" }, "total": { "type": "integer", "description": "Total number of audit entries for this mandate (-1 when unknown)" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dashboard/agents": { "get": { "operationId": "getEnterpriseAgents", "summary": "List agents for enterprise", "tags": [ "Dashboard" ], "description": "Returns agents that have mandates with this enterprise, including reputation scores and mandate counts. Supports sorting and filtering. Enterprise users are scoped to their own enterprise.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" }, { "schema": { "type": "string", "enum": [ "compositeScore", "mandateCount", "trustLevel", "displayName" ], "default": "compositeScore" }, "in": "query", "name": "sort", "required": false, "description": "Field to sort by" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "order", "required": false, "description": "Sort direction" }, { "schema": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "in": "query", "name": "trustLevel", "required": false, "description": "Filter by agent trust level" }, { "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "in": "query", "name": "minScore", "required": false, "description": "Minimum composite reputation score (0-1)" }, { "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "in": "query", "name": "maxScore", "required": false, "description": "Maximum composite reputation score (0-1)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of agents to return per page" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for pagination" } ], "responses": { "200": { "description": "Paginated list of agents associated with the enterprise.", "content": { "application/json": { "schema": { "description": "Paginated list of agents associated with the enterprise.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "trustLevel": { "type": "string" }, "compositeScore": { "type": [ "null", "number" ] }, "reliabilityScore": { "type": [ "null", "number" ] }, "totalMandates": { "type": "integer" }, "mandateCount": { "type": "integer" }, "activeCount": { "type": "integer" }, "errorCount": { "type": "integer" } }, "additionalProperties": false } }, "hasMore": { "type": "boolean", "description": "Whether more results exist beyond this page" }, "nextCursor": { "type": [ "null", "string" ], "description": "Cursor for the next page of results" }, "total": { "type": "integer", "description": "Total number of agents (-1 when using cursor pagination)" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dashboard/alerts": { "get": { "operationId": "getDashboardAlerts", "summary": "Get dashboard alerts (structuring detection, concurrent chains)", "tags": [ "Dashboard" ], "description": "Returns alerts for potential structuring activity (high-volume TXN mandates) and concurrent delegation chain warnings for the enterprise.\\n\\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24 }, "in": "query", "name": "windowHours", "required": false, "description": "Lookback window for structuring detection (hours)" }, { "schema": { "type": "integer", "minimum": 2, "maximum": 100, "default": 5 }, "in": "query", "name": "threshold", "required": false, "description": "Minimum mandate count to trigger structuring alert" } ], "responses": { "200": { "description": "Wrapped list of dashboard alerts.", "content": { "application/json": { "schema": { "description": "Wrapped list of dashboard alerts.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "structuring_detected", "concurrent_chains" ] }, "severity": { "type": "string", "enum": [ "warning", "info" ] }, "title": { "type": "string" }, "detail": { "type": "string" }, "agentId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "count": { "type": "integer" }, "mandateIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false } }, "hasMore": { "type": "boolean", "description": "Whether more results exist (always false for alerts)" }, "nextCursor": { "type": [ "null", "string" ], "description": "Cursor for the next page (always null for alerts)" }, "total": { "type": "integer", "description": "Total number of alerts" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dashboard/disputes": { "get": { "operationId": "getDashboardDisputes", "summary": "List disputes across enterprise mandates", "tags": [ "Dashboard" ], "description": "Returns disputes across all mandates for an enterprise, with optional status filter and cursor-based pagination. Enterprise users are scoped to their own enterprise.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" }, { "schema": { "type": "string", "enum": [ "OPEN", "TIER_1_REVIEW", "EVIDENCE_WINDOW", "TIER_2_REVIEW", "ESCALATED", "TIER_3_ARBITRATION", "RESOLVED", "DISMISSED", "WITHDRAWN" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by dispute status" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Pagination cursor from previous response" } ], "responses": { "200": { "description": "Paginated list of disputes.", "content": { "application/json": { "schema": { "description": "Paginated list of disputes.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "initiatedByRole": { "type": "string" }, "initiatedById": { "type": "string", "format": "uuid" }, "grounds": { "type": "string" }, "status": { "type": "string" }, "currentTier": { "type": "integer" }, "outcome": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "null", "string" ], "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of disputes (-1 when using cursor pagination)" }, "nextCursor": { "type": [ "null", "string" ] }, "hasMore": { "type": "boolean", "description": "Whether more results exist beyond this page" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/outcome": { "post": { "operationId": "reportOutcome", "summary": "Report principal verification outcome", "tags": [ "Verification" ], "description": "The principal (enterprise owner, principal agent, or platform) renders a PASS/FAIL verdict on a mandate. Accepts mandates in PROCESSING state (after receipt submission) or in gated mode after Phase 2 rules pass.\n\nStandard flow: receipt submitted → principal verdict → FULFILLED or FAILED.\nGated flow: rules pass → principal confirms (FULFILLED) or overturns (FAILED).\n\nRecords a verification result with `reporterType: \"principal\"` and emits verification.complete and settlement.signal events. Cascading verification is triggered if the mandate is a sub-mandate.\n\n**Auth:** enterprise (must own mandate), agent (must be principal), platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "receiptId", "outcome" ], "properties": { "receiptId": { "type": "string", "format": "uuid", "description": "Receipt being verified" }, "outcome": { "type": "string", "enum": [ "PASS", "FAIL" ], "description": "Verification outcome" }, "checks": { "type": "object", "additionalProperties": true, "description": "Optional per-field check results (principal-defined)" }, "notes": { "type": "string", "maxLength": 4000, "description": "Optional free-text notes explaining the principal's verdict (recorded in audit trail)" }, "reason": { "type": "string", "maxLength": 4000, "description": "Reason for the verdict (alias for notes — either field is accepted, notes takes precedence)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Outcome recorded. Mandate transitioned to FULFILLED or FAILED.", "content": { "application/json": { "schema": { "description": "Outcome recorded. Mandate transitioned to FULFILLED or FAILED.", "type": "object", "properties": { "mandateId": { "type": "string", "format": "uuid" }, "receiptId": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "PASS", "FAIL" ] }, "signal": { "type": "string", "enum": [ "SETTLE", "HOLD", "RELEASE" ] }, "reporterType": { "type": "string", "enum": [ "principal" ] }, "reportedAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "400": { "description": "Mandate not in PROCESSING state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate or receipt not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/verify": { "post": { "operationId": "triggerVerification", "summary": "Trigger explicit verification for a mandate", "tags": [ "Verification" ], "description": "Triggers verification for one or more receipts on a mandate. Returns current verification results for the specified receipts (or all receipts if none specified).\n\n**Auth:** enterprise, agent, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Verification result.", "content": { "application/json": { "schema": { "description": "Verification result.", "type": "object", "properties": { "mandateId": { "type": "string", "format": "uuid" }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "receiptId": { "type": "string", "format": "uuid" }, "phase1Result": { "type": [ "null", "object" ], "additionalProperties": true }, "phase2Result": { "type": [ "null", "object" ], "additionalProperties": true } }, "additionalProperties": false } }, "overallStatus": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/verification-status": { "get": { "operationId": "getVerificationStatus", "summary": "Get verification status for a mandate", "tags": [ "Verification" ], "description": "Returns Phase 1 and Phase 2 verification status, last verified timestamp, and any pending rules.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Verification status.", "content": { "application/json": { "schema": { "description": "Verification status.", "type": "object", "properties": { "mandateId": { "type": "string", "format": "uuid" }, "phase1Status": { "type": "string" }, "phase2Status": { "type": "string" }, "lastVerifiedAt": { "type": "string", "format": "date-time" }, "pendingRules": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/compliance-records": { "post": { "operationId": "createComplianceRecord", "summary": "Create a compliance attestation record", "tags": [ "Compliance" ], "description": "Records a deployer compliance attestation against a mandate. Required by EU AI Act for high-risk AI systems. Four record types are supported:\n\n- **workplace_notification**: Workers council / employee notification (Art. 26(7))\n- **affected_persons**: Affected persons notification (Art. 26(11))\n- **input_data_quality**: Input data quality review (Art. 26(4))\n- **fundamental_rights_impact_assessment**: Fundamental rights impact assessment (Art. 27)\n\nEach type requires specific attestation fields. Records are append-only and immutable.\n\n**Auth:** enterprise, platform (agents blocked — deployer obligation)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recordType", "attestation", "attestedBy" ], "properties": { "recordType": { "type": "string", "enum": [ "workplace_notification", "affected_persons", "input_data_quality", "fundamental_rights_impact_assessment" ], "description": "Type of compliance attestation" }, "attestation": { "type": "object", "additionalProperties": true, "description": "Attestation details (required fields vary by recordType)" }, "attestedBy": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name or identifier of the person attesting" }, "attestedAt": { "type": "string", "format": "date-time", "description": "When the attestation was made (defaults to now)" } }, "additionalProperties": false }, "examples": { "example1": { "value": { "recordType": "workplace_notification", "attestation": { "notification_date": "2026-03-01", "notification_method": "email", "workers_informed": "Engineering department (45 employees)" }, "attestedBy": "Jane Smith, HR Director" } }, "example2": { "value": { "recordType": "affected_persons", "attestation": { "categories": [ "job applicants", "current employees" ], "notification_method": "public notice", "notification_date": "2026-03-01" }, "attestedBy": "Legal Compliance Team" } }, "example3": { "value": { "recordType": "input_data_quality", "attestation": { "data_reviewed": true, "review_date": "2026-02-28", "data_sources": [ "internal HR database", "skills assessment platform" ] }, "attestedBy": "Data Quality Officer" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "201": { "description": "Compliance record created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": "string", "format": "uuid" }, "recordType": { "type": "string", "enum": [ "workplace_notification", "affected_persons", "input_data_quality", "fundamental_rights_impact_assessment" ] }, "attestation": { "type": "object", "additionalProperties": true }, "attestedBy": { "type": "string" }, "attestedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false, "description": "Compliance record created." } } } }, "400": { "description": "Missing required attestation fields or invalid record type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listComplianceRecords", "summary": "List compliance records for a mandate", "tags": [ "Compliance" ], "description": "Returns all compliance attestation records for the given mandate, ordered by creation date (newest first).\n\n**Auth:** enterprise, platform (agents blocked)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": "string", "format": "uuid" }, "recordType": { "type": "string", "enum": [ "workplace_notification", "affected_persons", "input_data_quality", "fundamental_rights_impact_assessment" ] }, "attestation": { "type": "object", "additionalProperties": true }, "attestedBy": { "type": "string" }, "attestedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/compliance-records/{recordId}": { "get": { "operationId": "getComplianceRecord", "summary": "Get a compliance record by ID", "tags": [ "Compliance" ], "description": "Retrieves a single compliance attestation record.\n\n**Auth:** enterprise, platform (agents blocked)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "recordId", "required": true } ], "responses": { "200": { "description": "Compliance record details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": "string", "format": "uuid" }, "recordType": { "type": "string", "enum": [ "workplace_notification", "affected_persons", "input_data_quality", "fundamental_rights_impact_assessment" ] }, "attestation": { "type": "object", "additionalProperties": true }, "attestedBy": { "type": "string" }, "attestedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Compliance record details." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Compliance record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/audit-export": { "get": { "operationId": "getAuditExport", "summary": "Export audit trail for a mandate", "tags": [ "Compliance" ], "description": "Generates a structured audit export for compliance record-keeping. Includes chain integrity verification (each entry links to the previous via SHA-256 hash). Payload hashes use RFC 8785 (JCS) canonicalization for cross-implementation consistency. When VAULT_SIGNING_KEY is configured, entries include Ed25519 per-entry signatures verifiable offline with the included public key.\n\nSupports three output formats: JSON (default), CSV, and NDJSON.\n\n**Auth:** enterprise, platform (agents blocked — deployer obligation)", "parameters": [ { "schema": { "type": "string", "enum": [ "json", "csv", "ndjson", "cose" ], "default": "json" }, "in": "query", "name": "format", "required": false, "description": "Export format: json (structured), csv (tabular), ndjson (one JSON object per line), cose (COSE_Sign1 — planned, returns 501)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "200": { "description": "Audit export (JSON format shown; CSV and NDJSON return raw text).", "content": { "application/json": { "schema": { "description": "Audit export (JSON format shown; CSV and NDJSON return raw text).", "type": "object", "properties": { "exportMetadata": { "type": "object", "properties": { "mandateId": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": [ "null", "string" ] }, "contractType": { "type": "string" }, "operatingMode": { "type": "string", "enum": [ "cleartext", "encrypted" ] }, "exportDate": { "type": "string", "format": "date-time" }, "totalEntries": { "type": "integer" }, "chainIntegrity": { "type": "boolean" }, "exportFormatVersion": { "type": "string" }, "canonicalization": { "type": "string" }, "signingPublicKey": { "type": [ "null", "string" ] }, "signingPublicKeys": { "type": "object", "additionalProperties": { "type": "string" }, "description": "All known signing public keys (keyId → base64 public key)" } }, "additionalProperties": false }, "entries": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "entryType": { "type": "string" }, "description": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "integrity": { "type": "object", "properties": { "payloadHash": { "type": "string" }, "hashAlg": { "type": "string", "description": "Hash algorithm used (e.g. SHA-256)" }, "previousHash": { "type": [ "null", "string" ] }, "signature": { "type": [ "null", "string" ] }, "signatureAlg": { "type": [ "null", "string" ], "description": "Signature algorithm used (e.g. Ed25519)" }, "signingKeyId": { "type": [ "null", "string" ] }, "valid": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/audit-vault/export": { "get": { "operationId": "bulkAuditVaultExport", "summary": "Bulk export audit vault entries", "tags": [ "Compliance" ], "description": "Paginated export of audit vault entries across mandates with chain verification metadata. Supports filtering by date range, mandate ID, and agent ID. Includes chain-of-custody metadata (first/last chain positions and hash chain validity). Supports JSON (default) and NDJSON output formats.\n\n**Auth:** enterprise, platform (agents blocked — deployer obligation)", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Include entries created at or after this timestamp" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "Include entries created before this timestamp" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "mandateId", "required": false, "description": "Filter by mandate ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "agentId", "required": false, "description": "Filter by agent ID (matches mandates where agent_id = this value)" }, { "schema": { "type": "string", "enum": [ "json", "ndjson" ], "default": "json" }, "in": "query", "name": "format", "required": false, "description": "Output format" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Pagination cursor (opaque, from previous response)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Max entries per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "entryType": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "payloadHash": { "type": "string" }, "hashAlg": { "type": "string", "description": "Hash algorithm used (e.g. SHA-256)" }, "previousHash": { "type": [ "null", "string" ] }, "chainPosition": { "type": "integer" }, "signature": { "type": [ "null", "string" ] }, "signatureAlg": { "type": [ "null", "string" ], "description": "Signature algorithm used (e.g. Ed25519)" }, "signingKeyId": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "chainMetadata": { "type": "object", "properties": { "firstPosition": { "type": [ "null", "integer" ] }, "lastPosition": { "type": [ "null", "integer" ] }, "hashChainValid": { "type": "boolean" } }, "additionalProperties": false }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "null", "string" ] } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/compliance/export": { "post": { "operationId": "createComplianceExport", "summary": "Initiate a compliance data export", "tags": [ "Compliance" ], "description": "Creates an export job for compliance data. Returns an export ID that can be polled for status.\n\n**Auth:** enterprise, platform (agents blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "format": { "type": "string", "enum": [ "csv", "json" ] }, "filters": { "type": "object", "properties": { "enterpriseId": { "type": "string", "format": "uuid" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "contractTypes": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Export initiated.", "content": { "application/json": { "schema": { "description": "Export initiated.", "type": "object", "properties": { "exportId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "processing", "ready" ] }, "downloadUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "recordCount": { "type": "integer" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/compliance/export/{exportId}": { "get": { "operationId": "getComplianceExport", "summary": "Get compliance export status", "tags": [ "Compliance" ], "description": "Check the status of a compliance export job and retrieve download URL when ready.\n\n**Auth:** enterprise, platform (agents blocked)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "exportId", "required": true } ], "responses": { "200": { "description": "Export status.", "content": { "application/json": { "schema": { "description": "Export status.", "type": "object", "properties": { "exportId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "processing", "ready", "failed" ] }, "downloadUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "recordCount": { "type": "integer" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Export not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/compliance/export/{exportId}/download": { "get": { "operationId": "downloadComplianceExport", "summary": "Download compliance export data", "tags": [ "Compliance" ], "description": "Returns the actual export data in the format specified at creation time (JSON or CSV). Export data expires 24 hours after creation.\n\n**Auth:** enterprise, platform (agents blocked)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "exportId", "required": true } ], "responses": { "200": { "description": "Export data (JSON object or CSV text depending on format).", "content": { "application/json": { "schema": { "description": "Export data (JSON object or CSV text depending on format).", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recordCount": { "type": "integer" }, "format": { "type": "string", "enum": [ "csv", "json" ] } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Export not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/ai-impact-assessment": { "post": { "operationId": "createAiImpactAssessment", "summary": "Create AI impact assessment for a mandate", "tags": [ "Compliance" ], "description": "Records an EU AI Act Article 9 impact assessment against a mandate. One assessment per mandate.\n\n**Auth:** enterprise, platform (agents blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "riskLevel", "domain" ], "properties": { "riskLevel": { "type": "string", "enum": [ "unacceptable", "high", "limited", "minimal" ] }, "domain": { "type": "string", "minLength": 1, "maxLength": 255 }, "humanOversight": { "type": "object", "additionalProperties": true }, "testingResults": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "201": { "description": "Assessment created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "riskLevel": { "type": "string", "enum": [ "unacceptable", "high", "limited", "minimal" ] }, "domain": { "type": "string" }, "overseerName": { "type": "string" }, "humanOversight": { "type": [ "null", "object" ], "additionalProperties": true }, "testingResults": { "type": [ "null", "object" ], "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false, "description": "Assessment created." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Assessment already exists for this mandate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getAiImpactAssessment", "summary": "Get AI impact assessment for a mandate", "tags": [ "Compliance" ], "description": "Retrieves the EU AI Act impact assessment for a mandate.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "200": { "description": "Assessment details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "riskLevel": { "type": "string", "enum": [ "unacceptable", "high", "limited", "minimal" ] }, "domain": { "type": "string" }, "overseerName": { "type": "string" }, "humanOversight": { "type": [ "null", "object" ], "additionalProperties": true }, "testingResults": { "type": [ "null", "object" ], "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Assessment details." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Assessment not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/compliance/eu-ai-act/report": { "get": { "operationId": "getEuAiActReport", "summary": "EU AI Act aggregate compliance report", "tags": [ "Compliance" ], "description": "Returns mandates with EU AI Act metadata and aggregate summary for the enterprise.\n\n**Auth:** enterprise, platform (agents blocked)", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" } ], "responses": { "200": { "description": "EU AI Act compliance report.", "content": { "application/json": { "schema": { "description": "EU AI Act compliance report.", "type": "object", "properties": { "mandates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "riskClassification": { "type": "string" }, "domain": { "type": "string" }, "humanOversightDesignated": { "type": "boolean" }, "assessmentDate": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "summary": { "type": "object", "properties": { "highRiskCount": { "type": "integer" }, "auditedCount": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{mandateId}/audit": { "get": { "operationId": "getMandateAudit", "summary": "Get audit trail for a mandate", "tags": [ "Compliance" ], "description": "Returns the tamper-evident audit trail (hash chain) for a mandate. Alias for GET /dashboard/audit-trail?mandateId=...\n\n**Auth:** enterprise, platform (agents blocked)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "afterPosition", "required": false }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "mandateId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mandateId": { "type": "string", "format": "uuid" }, "entryType": { "type": "string" }, "description": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "payloadHash": { "type": "string" }, "previousHash": { "type": [ "null", "string" ] }, "chainPosition": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "total": { "type": "integer" }, "nextCursor": { "type": [ "null", "string" ] } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/audit/enterprise-report": { "get": { "operationId": "getEnterpriseAuditExport", "summary": "Compliance Export — enterprise-wide audit data", "tags": [ "Audit" ], "description": "Returns comprehensive Compliance Export data for an enterprise: mandate lifecycle, dual-trail comparison, agent performance, verification results, disputes, alerts, and delegation statistics. Optimized for LLM-powered compliance analysis.\\n\\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Start of date range filter" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "End of date range filter" } ], "responses": { "200": { "description": "Compliance Export data.", "content": { "application/json": { "schema": { "description": "Compliance Export data.", "type": "object", "properties": { "metadata": { "type": "object", "properties": { "enterpriseId": { "type": "string", "format": "uuid" }, "exportDate": { "type": "string", "format": "date-time" }, "dateRange": { "type": [ "null", "object" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "formatVersion": { "type": "string" } }, "additionalProperties": false }, "mandateSummary": { "type": "object", "properties": { "total": { "type": "integer" }, "byStatus": { "type": "object", "additionalProperties": { "type": "integer" } }, "byContractType": { "type": "object", "additionalProperties": { "type": "integer" } }, "fulfillmentRate": { "type": [ "null", "number" ] }, "avgTimeToFulfillmentHours": { "type": [ "null", "number" ] } }, "additionalProperties": false }, "dualTrail": { "type": "object", "properties": { "explicitMandates": { "type": "integer" }, "sidecarMandates": { "type": "integer" }, "alignmentScore": { "type": "number" }, "byContractType": { "type": "array", "items": { "type": "object", "properties": { "contractType": { "type": "string" }, "explicit": { "type": "integer" }, "sidecar": { "type": "integer" }, "formalized": { "type": "integer" }, "unmatched": { "type": "integer" }, "uncovered": { "type": "integer" } }, "additionalProperties": false } }, "undeclaredTypes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "agents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "trustLevel": { "type": "string" }, "totalMandates": { "type": "integer" }, "activeMandates": { "type": "integer" }, "failedMandates": { "type": "integer" }, "verificationPassRate": { "type": [ "null", "number" ] }, "disputeCount": { "type": "integer" } }, "additionalProperties": false } }, "verification": { "type": "object", "properties": { "totalVerifications": { "type": "integer" }, "passRate": { "type": [ "null", "number" ] }, "avgTimeMs": { "type": [ "null", "number" ] }, "failuresByRule": { "type": "object", "additionalProperties": { "type": "integer" } } }, "additionalProperties": false }, "disputes": { "type": "object", "properties": { "total": { "type": "integer" }, "byStatus": { "type": "object", "additionalProperties": { "type": "integer" } }, "escalationRate": { "type": [ "null", "number" ] }, "avgResolutionTimeHours": { "type": [ "null", "number" ] } }, "additionalProperties": false }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "severity": { "type": "string", "enum": [ "warning", "info" ] }, "title": { "type": "string" }, "detail": { "type": "string" }, "agentId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "count": { "type": "integer" } }, "additionalProperties": false } }, "delegations": { "type": "object", "properties": { "totalChains": { "type": "integer" }, "maxDepth": { "type": "integer" }, "avgDepth": { "type": [ "null", "number" ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/audit/enterprise-report/analyze": { "post": { "operationId": "analyzeAuditReport", "summary": "Compliance Export analysis — LLM-powered", "tags": [ "Audit" ], "description": "Generates an AI-powered compliance analysis report from Compliance Export data. Uses Claude via AWS Bedrock to evaluate agent activity, identify risks, and produce actionable findings.\\n\\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Required for platform role" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Start of date range filter" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "End of date range filter" }, { "schema": { "type": "string" }, "in": "query", "name": "model", "required": false, "description": "Override Bedrock model ID (default: us.anthropic.claude-haiku-4-5-20251001-v1:0)" } ], "responses": { "200": { "description": "LLM-generated compliance analysis report.", "content": { "application/json": { "schema": { "description": "LLM-generated compliance analysis report.", "type": "object", "properties": { "riskLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "complianceScore": { "type": "number" }, "executiveSummary": { "type": "string" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "category": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "recommendation": { "type": "string" } }, "additionalProperties": false } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "modelUsed": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/projects": { "post": { "operationId": "createProject", "summary": "Create a project", "tags": [ "Projects" ], "description": "Create a new project to group mandates. Enterprise or platform auth required.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise ID (required for platform keys)" } ], "responses": { "201": { "description": "Project created.", "content": { "application/json": { "schema": { "description": "Project created.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listProjects", "summary": "List projects", "tags": [ "Projects" ], "description": "List projects for the authenticated enterprise. Supports status filter and pagination.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Enterprise ID (required for platform keys)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for cursor-based pagination (overrides offset when provided). Returned as nextCursor in previous response." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/projects/{id}": { "get": { "operationId": "getProject", "summary": "Get a project by ID", "tags": [ "Projects" ], "description": "Returns project details. Enterprise callers see only their own projects.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Project details.", "content": { "application/json": { "schema": { "description": "Project details.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateProject", "summary": "Update a project", "tags": [ "Projects" ], "description": "Update project name, description, or status. Agent keys cannot update projects.\n\n**Auth:** enterprise, platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Project updated.", "content": { "application/json": { "schema": { "description": "Project updated.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteProject", "summary": "Delete a project", "tags": [ "Projects" ], "description": "Permanently delete a project. Agent keys cannot delete projects.\n\n**Auth:** enterprise, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Project deleted." }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/graph": { "get": { "operationId": "getMandateGraph", "summary": "Get delegation chain graph for a mandate", "tags": [ "Mandates" ], "description": "Returns the delegation chain as nodes and edges for visualization. Walks parent_mandate_id chain upward and finds all sub-mandates recursively. Also includes informational depends_on edges.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Graph representation of the delegation chain.", "content": { "application/json": { "schema": { "description": "Graph representation of the delegation chain.", "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "type": "string" }, "agentId": { "type": [ "null", "string" ] }, "chainDepth": { "type": "integer" } }, "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "format": "uuid" }, "target": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "delegation", "dependency" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions": { "post": { "operationId": "createProxySession", "summary": "Register a proxy session", "tags": [ "Proxy" ], "description": "Creates a new proxy session record. Each proxy instance registers a session to group tool call observations.\n\n**Auth:** enterprise, agent (platform blocked from writes)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "startedAt", "proxyMode" ], "properties": { "proxyInstanceId": { "type": "string", "maxLength": 255, "default": "default", "description": "Identifier for the proxy instance" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the proxy session started (proxy clock)" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the proxy session ended (null if still active)" }, "proxyMode": { "type": "string", "enum": [ "observe", "advisory", "enforced" ], "description": "Proxy operating mode" }, "agentName": { "type": "string", "maxLength": 255, "description": "Display name of the observed agent" }, "agentExternalId": { "type": "string", "maxLength": 255, "description": "Customer-assigned external ID for the observed agent" }, "agentMetadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary string tags for the observed agent" }, "errorCount": { "type": "integer", "minimum": 0, "default": 0, "description": "Number of errored tool calls observed" }, "blockedCount": { "type": "integer", "minimum": 0, "default": 0, "description": "Number of blocked tool calls observed" }, "sessionOutcome": { "type": "string", "enum": [ "active", "zero_action", "undetected", "inactive" ], "default": "active", "description": "Session outcome: active (calls detected), zero_action (no calls), undetected (calls made but none matched), inactive (never ended)" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Proxy session created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "agentId": { "type": [ "null", "string" ], "format": "uuid" }, "proxyInstanceId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "format": "date-time" }, "totalCalls": { "type": "integer" }, "matchedCalls": { "type": "integer" }, "coveragePercent": { "type": "number" }, "sidecarMandateCount": { "type": "integer" }, "sidecarReceiptCount": { "type": "integer" }, "proxyMode": { "type": "string", "enum": [ "observe", "advisory", "enforced" ] }, "agentName": { "type": [ "null", "string" ] }, "agentExternalId": { "type": [ "null", "string" ] }, "agentMetadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" } }, "errorCount": { "type": "integer" }, "blockedCount": { "type": "integer" }, "sessionOutcome": { "type": "string", "enum": [ "active", "zero_action", "undetected", "inactive" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Proxy session created." } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listProxySessions", "summary": "List proxy sessions", "tags": [ "Proxy" ], "description": "Returns proxy sessions scoped to the requester. Enterprise users see their sessions; agents see theirs; platforms see all.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "enum": [ "observe", "advisory", "enforced" ] }, "in": "query", "name": "proxyMode", "required": false }, { "schema": { "type": "string", "enum": [ "active", "zero_action", "undetected", "inactive" ] }, "in": "query", "name": "sessionOutcome", "required": false }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "agentName", "required": false }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "agentExternalId", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor from nextCursor in previous response" } ], "responses": { "200": { "description": "Proxy sessions.", "content": { "application/json": { "schema": { "description": "Proxy sessions.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "agentId": { "type": [ "null", "string" ], "format": "uuid" }, "proxyInstanceId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "format": "date-time" }, "totalCalls": { "type": "integer" }, "matchedCalls": { "type": "integer" }, "coveragePercent": { "type": "number" }, "sidecarMandateCount": { "type": "integer" }, "sidecarReceiptCount": { "type": "integer" }, "proxyMode": { "type": "string", "enum": [ "observe", "advisory", "enforced" ] }, "agentName": { "type": [ "null", "string" ] }, "agentExternalId": { "type": [ "null", "string" ] }, "agentMetadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" } }, "errorCount": { "type": "integer" }, "blockedCount": { "type": "integer" }, "sessionOutcome": { "type": "string", "enum": [ "active", "zero_action", "undetected", "inactive" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of sessions (-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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sync": { "post": { "operationId": "syncProxySession", "summary": "Unified sync: session + all data in one request", "tags": [ "Proxy" ], "description": "Single-request sync for an entire proxy session. Creates session, ingests tool calls, sidecar mandates, sidecar receipts, and tool catalog in one transaction. Shadow receipts reference sidecar mandates by local proxy ID (e.g., SM-xxx); the backend translates to backend UUIDs internally. Returns a `mandateIdMap` for client-side reference.\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session" ], "properties": { "session": { "type": "object", "required": [ "startedAt", "proxyMode" ], "properties": { "proxyInstanceId": { "type": "string", "maxLength": 255, "default": "default" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "proxyMode": { "type": "string", "enum": [ "observe", "advisory", "enforced" ] }, "agentName": { "type": "string", "maxLength": 255 }, "agentExternalId": { "type": "string", "maxLength": 255 }, "agentMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "errorCount": { "type": "integer", "minimum": 0, "default": 0 }, "blockedCount": { "type": "integer", "minimum": 0, "default": 0 }, "sessionOutcome": { "type": "string", "enum": [ "active", "zero_action", "undetected", "inactive" ], "default": "active" } }, "additionalProperties": false }, "toolCalls": { "type": "array", "maxItems": 2000, "items": { "type": "object", "required": [ "toolName", "occurredAt" ], "properties": { "toolName": { "type": "string", "maxLength": 255 }, "upstreamName": { "type": "string", "maxLength": 255, "default": "unknown" }, "arguments": { "type": "object", "additionalProperties": true, "default": {} }, "result": { "type": [ "object", "null" ], "additionalProperties": true }, "durationMs": { "type": "integer", "minimum": 0, "default": 0 }, "patternMatch": { "type": [ "object", "null" ], "additionalProperties": true }, "sidecarMandateId": { "type": [ "string", "null" ] }, "sidecarReceiptId": { "type": [ "string", "null" ] }, "interceptorAction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED", "ANNOTATED" ], "default": "ALLOWED" }, "proxyToolCallId": { "type": [ "string", "null" ], "maxLength": 255 }, "occurredAt": { "type": "string", "format": "date-time" }, "isError": { "type": "boolean", "default": false }, "errorMessage": { "type": [ "string", "null" ], "maxLength": 4096 } }, "additionalProperties": false } }, "sidecarMandates": { "type": "array", "maxItems": 200, "items": { "type": "object", "required": [ "contractType", "confidence", "confidenceScore" ], "properties": { "contractType": { "type": "string", "maxLength": 50 }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "extractedCriteria": { "type": "object", "additionalProperties": true, "default": {} }, "sourceToolCallId": { "type": [ "string", "null" ], "format": "uuid" }, "proxySidecarMandateId": { "type": [ "string", "null" ], "maxLength": 255 }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "string", "null" ], "maxLength": 100 } }, "additionalProperties": false } }, "sidecarReceipts": { "type": "array", "maxItems": 200, "items": { "type": "object", "required": [ "sidecarMandateId", "confidence", "confidenceScore" ], "properties": { "sidecarMandateId": { "type": "string", "maxLength": 255 }, "extractedEvidence": { "type": "object", "additionalProperties": true, "default": {} }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "sourceToolCallId": { "type": [ "string", "null" ], "format": "uuid" }, "proxySidecarReceiptId": { "type": [ "string", "null" ], "maxLength": 255 } }, "additionalProperties": false } }, "toolCatalog": { "type": "array", "maxItems": 500, "items": { "type": "object", "required": [ "upstreamName", "toolName" ], "properties": { "upstreamName": { "type": "string", "maxLength": 255 }, "toolName": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 4096 }, "inputSchema": { "type": [ "object", "null" ], "additionalProperties": true }, "discoveredAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Unified sync result with all batch summaries and mandate ID map.", "content": { "application/json": { "schema": { "description": "Unified sync result with all batch summaries and mandate ID map.", "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "agentId": { "type": [ "null", "string" ], "format": "uuid" }, "proxyInstanceId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "format": "date-time" }, "totalCalls": { "type": "integer" }, "matchedCalls": { "type": "integer" }, "coveragePercent": { "type": "number" }, "sidecarMandateCount": { "type": "integer" }, "sidecarReceiptCount": { "type": "integer" }, "proxyMode": { "type": "string", "enum": [ "observe", "advisory", "enforced" ] }, "agentName": { "type": [ "null", "string" ] }, "agentExternalId": { "type": [ "null", "string" ] }, "agentMetadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" } }, "errorCount": { "type": "integer" }, "blockedCount": { "type": "integer" }, "sessionOutcome": { "type": "string", "enum": [ "active", "zero_action", "undetected", "inactive" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "toolCalls": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false }, "sidecarMandates": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false }, "sidecarReceipts": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false }, "toolCatalog": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false }, "mandateIdMap": { "type": "object", "additionalProperties": { "type": "string" } }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}": { "get": { "operationId": "getProxySession", "summary": "Get a proxy session by ID", "tags": [ "Proxy" ], "description": "Returns proxy session details including aggregated counts.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Proxy session details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "agentId": { "type": [ "null", "string" ], "format": "uuid" }, "proxyInstanceId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "null", "string" ], "format": "date-time" }, "totalCalls": { "type": "integer" }, "matchedCalls": { "type": "integer" }, "coveragePercent": { "type": "number" }, "sidecarMandateCount": { "type": "integer" }, "sidecarReceiptCount": { "type": "integer" }, "proxyMode": { "type": "string", "enum": [ "observe", "advisory", "enforced" ] }, "agentName": { "type": [ "null", "string" ] }, "agentExternalId": { "type": [ "null", "string" ] }, "agentMetadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" } }, "errorCount": { "type": "integer" }, "blockedCount": { "type": "integer" }, "sessionOutcome": { "type": "string", "enum": [ "active", "zero_action", "undetected", "inactive" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Proxy session details." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/tool-calls": { "post": { "operationId": "batchIngestToolCalls", "summary": "Batch ingest tool calls", "tags": [ "Proxy" ], "description": "Ingests up to 500 tool call observations for a proxy session. Deduplicates by `proxyToolCallId` (skipped items still appear in results). Session counts are recomputed after each batch.\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "toolName", "occurredAt" ], "properties": { "toolName": { "type": "string", "maxLength": 255 }, "upstreamName": { "type": "string", "maxLength": 255, "default": "unknown" }, "arguments": { "type": "object", "additionalProperties": true, "default": {} }, "result": { "type": [ "object", "null" ], "additionalProperties": true }, "durationMs": { "type": "integer", "minimum": 0, "default": 0 }, "patternMatch": { "type": [ "object", "null" ], "additionalProperties": true }, "sidecarMandateId": { "type": [ "string", "null" ] }, "sidecarReceiptId": { "type": [ "string", "null" ] }, "interceptorAction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED", "ANNOTATED" ], "default": "ALLOWED" }, "proxyToolCallId": { "type": [ "string", "null" ], "maxLength": 255 }, "occurredAt": { "type": "string", "format": "date-time" }, "isError": { "type": "boolean", "default": false }, "errorMessage": { "type": [ "string", "null" ], "maxLength": 4096 } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "207": { "description": "Multi-Status batch result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "skipped", "error" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "toolName": { "type": "string" }, "upstreamName": { "type": "string" }, "arguments": { "type": "object", "additionalProperties": true }, "result": { "type": [ "null", "object" ], "additionalProperties": true }, "durationMs": { "type": "integer" }, "patternMatch": { "type": [ "null", "object" ], "additionalProperties": true }, "sidecarMandateId": { "type": [ "null", "string" ] }, "sidecarReceiptId": { "type": [ "null", "string" ] }, "interceptorAction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED", "ANNOTATED" ] }, "proxyToolCallId": { "type": [ "null", "string" ] }, "isError": { "type": "boolean" }, "errorMessage": { "type": [ "null", "string" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "error": { "type": [ "null", "string" ] } }, "additionalProperties": false } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Multi-Status batch result." } } } }, "400": { "description": "Invalid input or batch too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getSessionToolCalls", "summary": "List tool calls for a session", "tags": [ "Proxy" ], "description": "Returns tool call observations for the given session, ordered by occurred_at ascending. Filter by tool name or error status to find specific tool calls.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor from nextCursor in previous response" }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "toolName", "required": false, "description": "Filter by tool name" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isError", "required": false, "description": "Filter by error status (true = errors only, false = successes only)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Tool calls.", "content": { "application/json": { "schema": { "description": "Tool calls.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "toolName": { "type": "string" }, "upstreamName": { "type": "string" }, "arguments": { "type": "object", "additionalProperties": true }, "result": { "type": [ "null", "object" ], "additionalProperties": true }, "durationMs": { "type": "integer" }, "patternMatch": { "type": [ "null", "object" ], "additionalProperties": true }, "sidecarMandateId": { "type": [ "null", "string" ] }, "sidecarReceiptId": { "type": [ "null", "string" ] }, "interceptorAction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED", "ANNOTATED" ] }, "proxyToolCallId": { "type": [ "null", "string" ] }, "isError": { "type": "boolean" }, "errorMessage": { "type": [ "null", "string" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of tool calls (-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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/sidecar-mandates": { "post": { "operationId": "ingestSidecarMandates", "summary": "Batch ingest sidecar mandates", "tags": [ "Proxy" ], "description": "Ingests up to 100 sidecar mandates detected by the proxy for a session. Deduplicates by `proxySidecarMandateId`.\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "contractType", "confidence", "confidenceScore" ], "properties": { "contractType": { "type": "string", "maxLength": 50 }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "extractedCriteria": { "type": "object", "additionalProperties": true, "default": {} }, "sourceToolCallId": { "type": [ "string", "null" ], "format": "uuid" }, "proxySidecarMandateId": { "type": [ "string", "null" ], "maxLength": 255 }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "string", "null" ], "maxLength": 100 } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "207": { "description": "Multi-Status batch result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "skipped", "error" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "extractedCriteria": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "sourceToolCallId": { "type": [ "null", "string" ] }, "formalizedMandateId": { "type": [ "null", "string" ] }, "proxySidecarMandateId": { "type": [ "null", "string" ] }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "null", "string" ], "maxLength": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "error": { "type": [ "null", "string" ] } }, "additionalProperties": false } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Multi-Status batch result." } } } }, "400": { "description": "Invalid input or batch too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getSessionSidecarMandates", "summary": "List sidecar mandates for a session", "tags": [ "Proxy" ], "description": "Returns sidecar mandates detected in the given session.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor from nextCursor in previous response" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Sidecar mandates.", "content": { "application/json": { "schema": { "description": "Sidecar mandates.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "extractedCriteria": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "sourceToolCallId": { "type": [ "null", "string" ] }, "formalizedMandateId": { "type": [ "null", "string" ] }, "proxySidecarMandateId": { "type": [ "null", "string" ] }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "null", "string" ], "maxLength": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of sidecar mandates (-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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/sidecar-receipts": { "post": { "operationId": "ingestSidecarReceipts", "summary": "Batch ingest sidecar receipts", "tags": [ "Proxy" ], "description": "Ingests up to 100 sidecar receipts for a session. Each receipt must reference a sidecar mandate in the same session. Deduplicates by `proxySidecarReceiptId`.\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "sidecarMandateId", "confidence", "confidenceScore" ], "properties": { "sidecarMandateId": { "type": "string", "format": "uuid" }, "extractedEvidence": { "type": "object", "additionalProperties": true, "default": {} }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "sourceToolCallId": { "type": [ "string", "null" ], "format": "uuid" }, "proxySidecarReceiptId": { "type": [ "string", "null" ], "maxLength": 255 } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "207": { "description": "Multi-Status batch result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "skipped", "error" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sidecarMandateId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "extractedEvidence": { "type": "object", "additionalProperties": true }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "sourceToolCallId": { "type": [ "null", "string" ] }, "proxySidecarReceiptId": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "error": { "type": [ "null", "string" ] } }, "additionalProperties": false } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Multi-Status batch result." } } } }, "400": { "description": "Invalid input or batch too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getSessionSidecarReceipts", "summary": "List sidecar receipts for a session", "tags": [ "Proxy" ], "description": "Returns sidecar receipts collected in the given session.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor from nextCursor in previous response" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Sidecar receipts.", "content": { "application/json": { "schema": { "description": "Sidecar receipts.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sidecarMandateId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "extractedEvidence": { "type": "object", "additionalProperties": true }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "sourceToolCallId": { "type": [ "null", "string" ] }, "proxySidecarReceiptId": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of sidecar receipts (-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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sidecar-mandates/{sidecarMandateId}": { "patch": { "operationId": "updateShadowMandate", "summary": "Update a sidecar mandate", "tags": [ "Proxy" ], "description": "Transitions a sidecar mandate from SHADOW to FORMALIZED (with a real mandate ID) or DISMISSED. Only SHADOW mandates can be updated.\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "FORMALIZED", "DISMISSED" ], "description": "New status" }, "formalizedMandateId": { "type": [ "string", "null" ], "format": "uuid", "description": "Real mandate ID (required when status is FORMALIZED)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sidecarMandateId", "required": true } ], "responses": { "200": { "description": "Updated sidecar mandate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "extractedCriteria": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "sourceToolCallId": { "type": [ "null", "string" ] }, "formalizedMandateId": { "type": [ "null", "string" ] }, "proxySidecarMandateId": { "type": [ "null", "string" ] }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "null", "string" ], "maxLength": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Updated sidecar mandate." } } } }, "400": { "description": "Invalid transition or missing formalizedMandateId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Sidecar mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sidecar-mandates": { "get": { "operationId": "listAllSidecarMandates", "summary": "List all sidecar mandates (cross-session)", "tags": [ "Proxy" ], "description": "Returns sidecar mandates across all sessions, scoped by ownership. Supports filtering by contract type, status, and minimum confidence score.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "maxLength": 50 }, "in": "query", "name": "contractType", "required": false }, { "schema": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "in": "query", "name": "confidenceMin", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor from nextCursor in previous response" } ], "responses": { "200": { "description": "Sidecar mandates.", "content": { "application/json": { "schema": { "description": "Sidecar mandates.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "extractedCriteria": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "sourceToolCallId": { "type": [ "null", "string" ] }, "formalizedMandateId": { "type": [ "null", "string" ] }, "proxySidecarMandateId": { "type": [ "null", "string" ] }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "null", "string" ], "maxLength": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of sidecar mandates (-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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/tool-catalog": { "post": { "operationId": "ingestToolCatalog", "summary": "Batch ingest tool catalog entries", "tags": [ "Proxy" ], "description": "Ingests up to 500 tool catalog entries for a session. Upserts by (session_id, upstream_name, tool_name).\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "upstreamName", "toolName" ], "properties": { "upstreamName": { "type": "string", "maxLength": 255 }, "toolName": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 4096 }, "inputSchema": { "type": [ "object", "null" ], "additionalProperties": true }, "discoveredAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "207": { "description": "Multi-Status batch result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "skipped", "error" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "upstreamName": { "type": "string" }, "toolName": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "inputSchema": { "type": [ "null", "object" ], "additionalProperties": true }, "discoveredAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "error": { "type": [ "null", "string" ] } }, "additionalProperties": false } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Multi-Status batch result." } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getSessionToolCatalog", "summary": "List tool catalog for a session", "tags": [ "Proxy" ], "description": "Returns the tool catalog (tools discovered via tools/list) for the given session.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Tool catalog entries.", "content": { "application/json": { "schema": { "description": "Tool catalog entries.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "upstreamName": { "type": "string" }, "toolName": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "inputSchema": { "type": [ "null", "object" ], "additionalProperties": true }, "discoveredAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/mandate-summary": { "get": { "operationId": "getSessionMandateSummary", "summary": "Get grouped mandate summary for a session", "tags": [ "Proxy" ], "description": "Returns sidecar mandates grouped by contract type for the given session. Each group includes count, confidence range, time range, and sample tool names. Use this for enterprise UX that shows \"3 procurement commitments\" instead of 3 rows.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Grouped mandate summaries.", "content": { "application/json": { "schema": { "description": "Grouped mandate summaries.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "contractType": { "type": "string" }, "count": { "type": "integer" }, "minConfidence": { "type": "number" }, "maxConfidence": { "type": "number" }, "avgConfidence": { "type": "number" }, "firstAt": { "type": "string", "format": "date-time" }, "lastAt": { "type": "string", "format": "date-time" }, "sampleToolNames": { "type": "array", "items": { "type": "string" } }, "statuses": { "type": "object", "additionalProperties": { "type": "integer" } } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/alignment": { "get": { "operationId": "getSessionAlignment", "summary": "Get dual-trail alignment for a session", "tags": [ "Proxy" ], "description": "Compares sidecar mandates (detected by proxy) with explicit mandates (registered via API) for a given session. Returns an alignment score and per-contract-type breakdown showing formalized, unmatched, and uncovered mandates.\n\n- **Formalized**: sidecar mandates linked to explicit mandates\n- **Unmatched**: sidecar mandates with no explicit counterpart (detected activity without formal agreement)\n- **Uncovered**: explicit mandates with no sidecar detection (formal agreements without detected activity)\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Session alignment analysis.", "content": { "application/json": { "schema": { "description": "Session alignment analysis.", "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid" }, "alignmentScore": { "type": "number", "description": "Percentage of actionable sidecar mandates that are formalized (0-100)" }, "totalSidecarMandates": { "type": "integer" }, "formalizedCount": { "type": "integer" }, "dismissedCount": { "type": "integer" }, "unmatchedCount": { "type": "integer" }, "totalExplicitMandates": { "type": "integer" }, "uncoveredCount": { "type": "integer" }, "byContractType": { "type": "array", "items": { "type": "object", "properties": { "contractType": { "type": "string" }, "sidecarCount": { "type": "integer" }, "formalizedCount": { "type": "integer" }, "dismissedCount": { "type": "integer" }, "unmatchedCount": { "type": "integer" }, "explicitCount": { "type": "integer" }, "uncoveredCount": { "type": "integer" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/shadow-mandates": { "post": { "operationId": "ingestSidecarMandates", "summary": "Batch ingest sidecar mandates", "tags": [ "Proxy" ], "description": "Ingests up to 100 sidecar mandates detected by the proxy for a session. Deduplicates by `proxySidecarMandateId`.\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "contractType", "confidence", "confidenceScore" ], "properties": { "contractType": { "type": "string", "maxLength": 50 }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "extractedCriteria": { "type": "object", "additionalProperties": true, "default": {} }, "sourceToolCallId": { "type": [ "string", "null" ], "format": "uuid" }, "proxySidecarMandateId": { "type": [ "string", "null" ], "maxLength": 255 }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "string", "null" ], "maxLength": 100 } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "207": { "description": "Multi-Status batch result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "skipped", "error" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "extractedCriteria": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "sourceToolCallId": { "type": [ "null", "string" ] }, "formalizedMandateId": { "type": [ "null", "string" ] }, "proxySidecarMandateId": { "type": [ "null", "string" ] }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "null", "string" ], "maxLength": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "error": { "type": [ "null", "string" ] } }, "additionalProperties": false } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Multi-Status batch result." } } } }, "400": { "description": "Invalid input or batch too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getSessionSidecarMandates", "summary": "List sidecar mandates for a session", "tags": [ "Proxy" ], "description": "Returns sidecar mandates detected in the given session.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor from nextCursor in previous response" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Sidecar mandates.", "content": { "application/json": { "schema": { "description": "Sidecar mandates.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "extractedCriteria": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "sourceToolCallId": { "type": [ "null", "string" ] }, "formalizedMandateId": { "type": [ "null", "string" ] }, "proxySidecarMandateId": { "type": [ "null", "string" ] }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "null", "string" ], "maxLength": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of sidecar mandates (-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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/shadow-receipts": { "post": { "operationId": "ingestSidecarReceipts", "summary": "Batch ingest sidecar receipts", "tags": [ "Proxy" ], "description": "Ingests up to 100 sidecar receipts for a session. Each receipt must reference a sidecar mandate in the same session. Deduplicates by `proxySidecarReceiptId`.\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "sidecarMandateId", "confidence", "confidenceScore" ], "properties": { "sidecarMandateId": { "type": "string", "format": "uuid" }, "extractedEvidence": { "type": "object", "additionalProperties": true, "default": {} }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "sourceToolCallId": { "type": [ "string", "null" ], "format": "uuid" }, "proxySidecarReceiptId": { "type": [ "string", "null" ], "maxLength": 255 } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "207": { "description": "Multi-Status batch result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "skipped", "error" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sidecarMandateId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "extractedEvidence": { "type": "object", "additionalProperties": true }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "sourceToolCallId": { "type": [ "null", "string" ] }, "proxySidecarReceiptId": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "error": { "type": [ "null", "string" ] } }, "additionalProperties": false } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Multi-Status batch result." } } } }, "400": { "description": "Invalid input or batch too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getSessionSidecarReceipts", "summary": "List sidecar receipts for a session", "tags": [ "Proxy" ], "description": "Returns sidecar receipts collected in the given session.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor from nextCursor in previous response" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Sidecar receipts.", "content": { "application/json": { "schema": { "description": "Sidecar receipts.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sidecarMandateId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "extractedEvidence": { "type": "object", "additionalProperties": true }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "sourceToolCallId": { "type": [ "null", "string" ] }, "proxySidecarReceiptId": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of sidecar receipts (-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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/shadow-mandates": { "get": { "operationId": "listAllSidecarMandates", "summary": "List all sidecar mandates (cross-session)", "tags": [ "Proxy" ], "description": "Returns sidecar mandates across all sessions, scoped by ownership. Supports filtering by contract type, status, and minimum confidence score.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "maxLength": 50 }, "in": "query", "name": "contractType", "required": false }, { "schema": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "in": "query", "name": "confidenceMin", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor from nextCursor in previous response" } ], "responses": { "200": { "description": "Sidecar mandates.", "content": { "application/json": { "schema": { "description": "Sidecar mandates.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "extractedCriteria": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "sourceToolCallId": { "type": [ "null", "string" ] }, "formalizedMandateId": { "type": [ "null", "string" ] }, "proxySidecarMandateId": { "type": [ "null", "string" ] }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "null", "string" ], "maxLength": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "total": { "type": "integer", "description": "Total number of sidecar mandates (-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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/shadow-mandates/{sidecarMandateId}": { "patch": { "operationId": "updateShadowMandate", "summary": "Update a sidecar mandate", "tags": [ "Proxy" ], "description": "Transitions a sidecar mandate from SHADOW to FORMALIZED (with a real mandate ID) or DISMISSED. Only SHADOW mandates can be updated.\n\n**Auth:** enterprise, agent (platform blocked)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "FORMALIZED", "DISMISSED" ], "description": "New status" }, "formalizedMandateId": { "type": [ "string", "null" ], "format": "uuid", "description": "Real mandate ID (required when status is FORMALIZED)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sidecarMandateId", "required": true } ], "responses": { "200": { "description": "Updated sidecar mandate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "contractType": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "confidenceScore": { "type": "number" }, "extractedCriteria": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "SHADOW", "FORMALIZED", "DISMISSED" ] }, "sourceToolCallId": { "type": [ "null", "string" ] }, "formalizedMandateId": { "type": [ "null", "string" ] }, "proxySidecarMandateId": { "type": [ "null", "string" ] }, "batchCount": { "type": "integer", "minimum": 1, "default": 1 }, "ruleId": { "type": [ "null", "string" ], "maxLength": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Updated sidecar mandate." } } } }, "400": { "description": "Invalid transition or missing formalizedMandateId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Sidecar mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/analytics": { "get": { "operationId": "getAnalyticsSummary", "summary": "Get cross-session analytics summary", "tags": [ "Proxy" ], "description": "Returns aggregated analytics across all proxy sessions for the requester. Filterable by agent, date range, and proxy mode.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "agentExternalId", "required": false }, { "schema": { "type": "string", "enum": [ "observe", "advisory", "enforced" ] }, "in": "query", "name": "proxyMode", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false } ], "responses": { "200": { "description": "Aggregated analytics summary.", "content": { "application/json": { "schema": { "description": "Aggregated analytics summary.", "type": "object", "properties": { "totalSessions": { "type": "integer" }, "zeroActionSessions": { "type": "integer" }, "totalCalls": { "type": "integer" }, "totalErrors": { "type": "integer" }, "totalBlocked": { "type": "integer" }, "avgCoveragePercent": { "type": "number" }, "distinctTools": { "type": "integer" }, "distinctUpstreams": { "type": "integer" }, "contractTypeBreakdown": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Count of sidecar mandates by contract type across all sessions" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/sessions/{sessionId}/analytics": { "get": { "operationId": "getSessionAnalytics", "summary": "Get session analytics", "tags": [ "Proxy" ], "description": "Returns aggregated analytics for a proxy session: call counts, error rates, tool distribution, timing metrics.\n\n**Auth:** enterprise, agent, platform (scoped by ownership)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Session analytics.", "content": { "application/json": { "schema": { "description": "Session analytics.", "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid" }, "totalCalls": { "type": "integer" }, "errorCount": { "type": "integer" }, "blockedCount": { "type": "integer" }, "matchedCalls": { "type": "integer" }, "coveragePercent": { "type": "number" }, "avgDurationMs": { "type": "number" }, "maxDurationMs": { "type": "integer" }, "distinctTools": { "type": "integer" }, "distinctUpstreams": { "type": "integer" }, "callsByTool": { "type": "object", "additionalProperties": { "type": "integer" } }, "errorsByTool": { "type": "object", "additionalProperties": { "type": "integer" } }, "estimatedTokenOverhead": { "type": "object", "properties": { "annotatedCalls": { "type": "integer" }, "estimatedTokens": { "type": "integer" }, "avgTokensPerAnnotation": { "type": "integer" }, "disclaimer": { "type": "string" } }, "additionalProperties": false }, "contractTypeBreakdown": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Count of sidecar mandates by contract type" }, "confidenceDistribution": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Count of sidecar mandates by confidence level (low/medium/high)" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/proxy/analytics/summary": { "get": { "operationId": "getAnalyticsSummary", "summary": "Get cross-session analytics summary", "tags": [ "Proxy" ], "description": "Returns aggregated analytics across all proxy sessions for the requester. Filterable by agent, date range, and proxy mode.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "agentExternalId", "required": false }, { "schema": { "type": "string", "enum": [ "observe", "advisory", "enforced" ] }, "in": "query", "name": "proxyMode", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false } ], "responses": { "200": { "description": "Aggregated analytics summary.", "content": { "application/json": { "schema": { "description": "Aggregated analytics summary.", "type": "object", "properties": { "totalSessions": { "type": "integer" }, "zeroActionSessions": { "type": "integer" }, "totalCalls": { "type": "integer" }, "totalErrors": { "type": "integer" }, "totalBlocked": { "type": "integer" }, "avgCoveragePercent": { "type": "number" }, "distinctTools": { "type": "integer" }, "distinctUpstreams": { "type": "integer" }, "contractTypeBreakdown": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Count of sidecar mandates by contract type across all sessions" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/register": { "post": { "operationId": "registerAccount", "summary": "Register a new account", "tags": [ "Auth" ], "description": "Creates an enterprise or agent account and returns a one-time API key. No authentication required. The API key is shown once and cannot be recovered. New accounts start in sandbox mode with restricted access. Provide an email (for enterprises/agents) or agentCardUrl (for agents) to verify and unlock full access. Rate limited to 10 requests per 15 minutes per IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role", "name" ], "properties": { "role": { "type": "string", "enum": [ "enterprise", "agent" ], "description": "Account type. Platform accounts require manual provisioning." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name for the enterprise or agent." }, "email": { "type": "string", "format": "email", "maxLength": 320, "description": "Contact email. If provided, a verification email is sent to unlock full access." }, "agentCardUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "A2A AgentCard URL (agent role only). Must be HTTPS and end with /.well-known/agent-card.json or /.well-known/agent.json. If valid, the agent is verified immediately on registration." }, "enterpriseId": { "type": "string", "format": "uuid", "description": "Enterprise ID to auto-approve this agent for (agent role only)." } }, "additionalProperties": false } } } }, "security": [], "responses": { "201": { "description": "Account created. API key is shown once — store it securely.", "content": { "application/json": { "schema": { "description": "Account created. API key is shown once — store it securely.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Enterprise or agent ID." }, "apiKey": { "type": "string", "description": "API key (plaintext, shown once). Use as Bearer token." }, "role": { "type": "string", "enum": [ "enterprise", "agent" ] }, "name": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ], "description": "Current trust level. sandbox = restricted access until verified." }, "verificationPending": { "type": [ "null", "string" ], "enum": [ "email", null ], "description": "If present, a verification email was sent. Click the link to unlock full access." }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls to complete account setup" } }, "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid role, missing/invalid name, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded or global registration ceiling reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/enterprise": { "post": { "operationId": "registerEnterprise", "summary": "Register a new enterprise account", "tags": [ "Auth" ], "description": "Alias for POST /auth/register with role=enterprise. Creates an enterprise account and returns a one-time API key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name for the enterprise or agent." }, "email": { "type": "string", "format": "email", "maxLength": 320, "description": "Contact email. If provided, a verification email is sent to unlock full access." } }, "additionalProperties": false } } } }, "security": [], "responses": { "201": { "description": "Account created. API key is shown once — store it securely.", "content": { "application/json": { "schema": { "description": "Account created. API key is shown once — store it securely.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Enterprise or agent ID." }, "apiKey": { "type": "string", "description": "API key (plaintext, shown once). Use as Bearer token." }, "role": { "type": "string", "enum": [ "enterprise", "agent" ] }, "name": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ], "description": "Current trust level. sandbox = restricted access until verified." }, "verificationPending": { "type": [ "null", "string" ], "enum": [ "email", null ], "description": "If present, a verification email was sent. Click the link to unlock full access." }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls to complete account setup" } }, "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid role, missing/invalid name, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded or global registration ceiling reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/agent": { "post": { "operationId": "registerAgent", "summary": "Register a new agent account", "tags": [ "Auth" ], "description": "Alias for POST /auth/register with role=agent. Creates an agent account and returns a one-time API key. If enterpriseId is provided, automatically approves the agent for that enterprise.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name for the enterprise or agent." }, "email": { "type": "string", "format": "email", "maxLength": 320, "description": "Contact email. If provided, a verification email is sent to unlock full access." }, "agentCardUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "A2A AgentCard URL (agent role only). Must be HTTPS and end with /.well-known/agent-card.json or /.well-known/agent.json. If valid, the agent is verified immediately on registration." }, "enterpriseId": { "type": "string", "format": "uuid", "description": "Enterprise ID to auto-approve this agent for." }, "agentClass": { "type": "string", "enum": [ "personal", "system", "team", "ephemeral" ], "description": "Agent classification: personal (human-owned), system (always-on), team (shared), ephemeral (per-task). Default: system." }, "ownerRef": { "type": "string", "maxLength": 320, "description": "Owner identity (email or identity URI of responsible person/team)" }, "orgUnit": { "type": "string", "maxLength": 255, "description": "Organizational unit (department, team, cost center)" }, "description": { "type": "string", "maxLength": 2000, "description": "Plain-text description of what this agent does" } }, "additionalProperties": false } } } }, "security": [], "responses": { "201": { "description": "Account created. API key is shown once — store it securely.", "content": { "application/json": { "schema": { "description": "Account created. API key is shown once — store it securely.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Enterprise or agent ID." }, "apiKey": { "type": "string", "description": "API key (plaintext, shown once). Use as Bearer token." }, "role": { "type": "string", "enum": [ "enterprise", "agent" ] }, "name": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ], "description": "Current trust level. sandbox = restricted access until verified." }, "verificationPending": { "type": [ "null", "string" ], "enum": [ "email", null ], "description": "If present, a verification email was sent. Click the link to unlock full access." }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next API calls to complete account setup" } }, "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid role, missing/invalid name, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded or global registration ceiling reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/keys/rotate": { "post": { "operationId": "rotateApiKey", "summary": "Rotate API key", "tags": [ "Auth" ], "description": "Deactivates the current API key and issues a new one. The new key is returned once — store it securely. The old key is immediately deactivated.", "responses": { "200": { "description": "New API key (shown once). The previous key has been deactivated.", "content": { "application/json": { "schema": { "description": "New API key (shown once). The previous key has been deactivated.", "type": "object", "properties": { "apiKey": { "type": "string", "description": "New API key (plaintext, shown once). Use as Bearer token." }, "role": { "type": "string" }, "previousKeyDeactivated": { "type": "boolean" } }, "additionalProperties": false } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/verify": { "get": { "operationId": "verifyEmail", "summary": "Verify email address", "tags": [ "Auth" ], "description": "Email verification callback. Click the link from the verification email to upgrade your account from sandbox to verified. No authentication required (token is self-authenticating). Rate limited to 10 requests per 15 minutes per IP.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096 }, "in": "query", "name": "token", "required": true } ], "security": [], "responses": { "200": { "description": "Email verified. Account upgraded.", "content": { "application/json": { "schema": { "description": "Email verified. Account upgraded.", "type": "object", "properties": { "message": { "type": "string" }, "accountId": { "type": "string", "format": "uuid" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] } }, "additionalProperties": false } } } }, "400": { "description": "Invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/verify-email": { "post": { "operationId": "sendVerificationEmail", "summary": "Request verification email", "tags": [ "Auth" ], "description": "Send a verification email for the authenticated account. Only available for sandbox accounts. Rate limited to 3 requests per 15 minutes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Verification email sent.", "content": { "application/json": { "schema": { "description": "Verification email sent.", "type": "object", "properties": { "message": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/verify-agent-card": { "post": { "operationId": "verifyAgentCard", "summary": "Verify via AgentCard", "tags": [ "Auth" ], "description": "Verify an agent account by providing an A2A AgentCard URL. Agent role only, sandbox accounts only. The server fetches and validates the AgentCard, then upgrades the account to verified. Rate limited to 5 requests per 15 minutes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentCardUrl" ], "properties": { "agentCardUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS URL ending with /.well-known/agent-card.json or /.well-known/agent.json" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "AgentCard verified. Account upgraded to verified.", "content": { "application/json": { "schema": { "description": "AgentCard verified. Account upgraded to verified.", "type": "object", "properties": { "message": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "verified" ] }, "agentCardName": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "AgentCard validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/me": { "get": { "operationId": "getMe", "summary": "Get authenticated user profile", "tags": [ "Auth" ], "description": "Returns the profile of the currently authenticated user based on the Bearer token. Enterprise accounts include name, email, and verification status from the enterprises table. Agent accounts include display name, email, and verification status from the agents table. Platform accounts return null for profile fields (no backing row).\n\n**Auth:** enterprise, agent, platform", "responses": { "200": { "description": "Authenticated user profile.", "content": { "application/json": { "schema": { "description": "Authenticated user profile.", "type": "object", "properties": { "apiKeyId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "enterprise", "agent", "platform" ] }, "ownerId": { "type": "string", "format": "uuid" }, "ownerType": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "scopes": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Key scopes. null = full access for role." }, "expiresAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Key expiry timestamp. null = no expiry." }, "allowedIps": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "IP allowlist. null = any IP allowed." }, "name": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "createdAt": { "type": [ "null", "string" ], "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notarize/mandates": { "post": { "operationId": "notarizeMandate", "summary": "Notarize a mandate", "tags": [ "Notarization" ], "description": "Accepts a mandate payload, computes SHA-256 hash of the JCS-canonicalized content, stores the hash with metadata (NOT the full payload), and returns the payload + hash + ID. The caller retains the payload; AGLedger holds proof the agreement was witnessed.\n\n**Auth:** enterprise or agent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payload", "contractType" ], "properties": { "payload": { "type": "object", "additionalProperties": true, "description": "Mandate payload (echoed back, not stored)" }, "contractType": { "type": "string", "maxLength": 50 }, "performerId": { "type": "string", "format": "uuid", "description": "Agent who will perform the mandate" }, "performerHint": { "type": "string", "format": "uuid", "description": "Alias for performerId (deprecated, use performerId)" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Non-sensitive metadata stored alongside the hash" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Mandate notarized. Payload echoed back with hash and ID.", "content": { "application/json": { "schema": { "description": "Mandate notarized. Payload echoed back with hash and ID.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payloadHash": { "type": "string", "description": "SHA-256 hex of JCS-canonicalized payload" }, "contractType": { "type": "string" }, "principalId": { "type": "string", "format": "uuid" }, "principalRole": { "type": "string", "enum": [ "enterprise", "agent" ] }, "performerId": { "type": [ "null", "string" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "NOTARIZED", "ACCEPTED", "COUNTER_PROPOSED", "REJECTED", "RECEIPT_SUBMITTED", "VERDICT_PASS", "VERDICT_FAIL" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": true } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notarize/mandates/{id}": { "get": { "operationId": "getNotarizedMandate", "summary": "Get a notarized mandate", "tags": [ "Notarization" ], "description": "Returns the notarized mandate metadata (hash, status, participants). Does NOT return the original payload.\n\n**Auth:** principal, performer, or platform.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Notarized mandate metadata.", "content": { "application/json": { "schema": { "description": "Notarized mandate metadata.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payloadHash": { "type": "string", "description": "SHA-256 hex of JCS-canonicalized payload" }, "contractType": { "type": "string" }, "principalId": { "type": "string", "format": "uuid" }, "principalRole": { "type": "string", "enum": [ "enterprise", "agent" ] }, "performerId": { "type": [ "null", "string" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "NOTARIZED", "ACCEPTED", "COUNTER_PROPOSED", "REJECTED", "RECEIPT_SUBMITTED", "VERDICT_PASS", "VERDICT_FAIL" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Notarized mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notarize/mandates/{id}/history": { "get": { "operationId": "getNotarizedMandateHistory", "summary": "Get notarized mandate transition history", "tags": [ "Notarization" ], "description": "Returns the full state transition history for a notarized mandate.\n\n**Auth:** principal, performer, or platform.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "State transition history.", "content": { "application/json": { "schema": { "description": "State transition history.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fromStatus": { "type": [ "null", "string" ] }, "toStatus": { "type": "string" }, "actorId": { "type": "string", "format": "uuid" }, "actorRole": { "type": "string" }, "payloadHash": { "type": [ "null", "string" ] }, "reason": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Notarized mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notarize/mandates/{id}/accept": { "post": { "operationId": "acceptNotarizedMandate", "summary": "Accept a notarized mandate", "tags": [ "Notarization" ], "description": "The performer accepts the mandate. Records a state transition with timestamp.\n\n**Auth:** agent (must be designated performer) or platform.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 2000, "description": "Optional acceptance message" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Mandate accepted.", "content": { "application/json": { "schema": { "description": "Mandate accepted.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payloadHash": { "type": "string", "description": "SHA-256 hex of JCS-canonicalized payload" }, "contractType": { "type": "string" }, "principalId": { "type": "string", "format": "uuid" }, "principalRole": { "type": "string", "enum": [ "enterprise", "agent" ] }, "performerId": { "type": [ "null", "string" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "NOTARIZED", "ACCEPTED", "COUNTER_PROPOSED", "REJECTED", "RECEIPT_SUBMITTED", "VERDICT_PASS", "VERDICT_FAIL" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": true } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Notarized mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid state transition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notarize/mandates/{id}/counter-propose": { "post": { "operationId": "counterProposeNotarizedMandate", "summary": "Counter-propose on a notarized mandate", "tags": [ "Notarization" ], "description": "The performer submits counter-terms. The counter-proposal payload is hashed and stored; the original hash is preserved in the transition history.\n\n**Auth:** agent (must be designated performer) or platform.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payload" ], "properties": { "payload": { "type": "object", "additionalProperties": true, "description": "Counter-proposal payload (echoed back, not stored)" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Counter-proposal recorded.", "content": { "application/json": { "schema": { "description": "Counter-proposal recorded.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payloadHash": { "type": "string", "description": "SHA-256 hex of JCS-canonicalized payload" }, "contractType": { "type": "string" }, "principalId": { "type": "string", "format": "uuid" }, "principalRole": { "type": "string", "enum": [ "enterprise", "agent" ] }, "performerId": { "type": [ "null", "string" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "NOTARIZED", "ACCEPTED", "COUNTER_PROPOSED", "REJECTED", "RECEIPT_SUBMITTED", "VERDICT_PASS", "VERDICT_FAIL" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": true } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Notarized mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid state transition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notarize/mandates/{id}/receipts": { "post": { "operationId": "submitNotarizedReceipt", "summary": "Submit a notarized receipt", "tags": [ "Notarization" ], "description": "The performer submits evidence of completion. The receipt payload is hashed and stored; the full payload is echoed back but not persisted.\n\n**Auth:** agent (must be designated performer) or platform.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payload" ], "properties": { "payload": { "type": "object", "additionalProperties": true, "description": "Receipt payload (echoed back, not stored)" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Receipt notarized.", "content": { "application/json": { "schema": { "description": "Receipt notarized.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "notarizedMandateId": { "type": "string", "format": "uuid" }, "payloadHash": { "type": "string" }, "performerId": { "type": "string", "format": "uuid" }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": true } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Notarized mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid state transition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notarize/mandates/{id}/verdict": { "post": { "operationId": "renderNotarizationVerdict", "summary": "Render verdict on a notarized mandate", "tags": [ "Notarization" ], "description": "The principal renders PASS or FAIL. Records the verdict as a state transition.\n\n**Auth:** enterprise or agent (must be mandate principal) or platform.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "verdict" ], "properties": { "verdict": { "type": "string", "enum": [ "PASS", "FAIL" ] }, "reason": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Verdict recorded.", "content": { "application/json": { "schema": { "description": "Verdict recorded.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payloadHash": { "type": "string", "description": "SHA-256 hex of JCS-canonicalized payload" }, "contractType": { "type": "string" }, "principalId": { "type": "string", "format": "uuid" }, "principalRole": { "type": "string", "enum": [ "enterprise", "agent" ] }, "performerId": { "type": [ "null", "string" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "NOTARIZED", "ACCEPTED", "COUNTER_PROPOSED", "REJECTED", "RECEIPT_SUBMITTED", "VERDICT_PASS", "VERDICT_FAIL" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": true } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Notarized mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid state transition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notarize/verify": { "post": { "operationId": "verifyNotarizedPayload", "summary": "Verify a payload against a stored hash", "tags": [ "Notarization" ], "description": "Submit your copy of a mandate or receipt payload. AGLedger hashes it and compares against the stored hash. Returns match/mismatch — enables dispute resolution without AGLedger holding the original data.\n\n**Auth:** any authenticated user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payload" ], "properties": { "notarizedMandateId": { "type": "string", "format": "uuid" }, "notarizedReceiptId": { "type": "string", "format": "uuid" }, "payload": { "type": "object", "additionalProperties": true, "description": "Your copy of the payload to verify" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Hash comparison result.", "content": { "application/json": { "schema": { "description": "Hash comparison result.", "type": "object", "properties": { "match": { "type": "boolean", "description": "Whether your payload matches the stored hash" }, "storedHash": { "type": "string" }, "computedHash": { "type": "string" }, "notarizedAt": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "mandate", "receipt" ] } }, "additionalProperties": false } } } }, "400": { "description": "Must provide notarizedMandateId or notarizedReceiptId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Notarized record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/enterprises/{enterpriseId}/agents/{agentId}": { "put": { "operationId": "approveEnterpriseAgent", "summary": "Approve an agent for this enterprise", "tags": [ "Enterprise Agents" ], "description": "Register an agent as approved to receive mandates from this enterprise. If the agent was previously suspended or revoked, this re-approves them.\n\n**Auth:** enterprise (own enterprise) or platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000, "description": "Justification for approval (recorded in audit trail)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "enterpriseId", "required": true }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Agent already approved (idempotent) or re-approved from suspended/revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enterpriseId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "approved", "suspended", "revoked" ] }, "approvedBy": { "type": [ "null", "string" ] }, "approvedAt": { "type": "string", "format": "date-time" }, "suspendedAt": { "type": [ "null", "string" ], "format": "date-time" }, "revokedAt": { "type": [ "null", "string" ], "format": "date-time" }, "reason": { "type": [ "null", "string" ] }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions after approving the agent" } }, "additionalProperties": false, "description": "Agent already approved (idempotent) or re-approved from suspended/revoked." } } } }, "201": { "description": "Agent newly approved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enterpriseId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "approved", "suspended", "revoked" ] }, "approvedBy": { "type": [ "null", "string" ] }, "approvedAt": { "type": "string", "format": "date-time" }, "suspendedAt": { "type": [ "null", "string" ], "format": "date-time" }, "revokedAt": { "type": [ "null", "string" ], "format": "date-time" }, "reason": { "type": [ "null", "string" ] }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions after approving the agent" } }, "additionalProperties": false, "description": "Agent newly approved." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "revokeEnterpriseAgent", "summary": "Revoke an agent from this enterprise", "tags": [ "Enterprise Agents" ], "description": "Revoke an agent so they can no longer receive new mandates from this enterprise. In-flight mandates are not affected.\n\n**Auth:** enterprise (own enterprise) or platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000, "description": "Justification for revocation (recorded in audit trail)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "enterpriseId", "required": true }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "204": { "description": "Agent revoked." }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found in enterprise registry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateEnterpriseAgentStatus", "summary": "Suspend or reinstate an agent", "tags": [ "Enterprise Agents" ], "description": "Update an agent's status within the enterprise. Use `suspended` to temporarily block new mandates, or `approved` to reinstate.\n\n**Auth:** enterprise (own enterprise) or platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "suspended", "approved" ], "description": "New status for the agent" }, "reason": { "type": "string", "maxLength": 1000, "description": "Justification for status change (recorded in audit trail)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "enterpriseId", "required": true }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Agent status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseAgent" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found in enterprise registry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getEnterpriseAgent", "summary": "Get agent approval status", "tags": [ "Enterprise Agents" ], "description": "Returns the approval record for a specific agent within this enterprise.\n\n**Auth:** enterprise (own enterprise) or platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "enterpriseId", "required": true }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Agent approval record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseAgent" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found in enterprise registry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/enterprises/{enterpriseId}/agents/bulk": { "post": { "operationId": "bulkApproveEnterpriseAgents", "summary": "Bulk approve agents", "tags": [ "Enterprise Agents" ], "description": "Approve multiple agents for this enterprise in a single operation. Agents already approved are updated (idempotent). Suspended/revoked agents are re-approved. Maximum 100 agents per request.\n\n**Auth:** enterprise (own enterprise) or platform. Blocked when `approvalRequiresPlatformKey` is true and caller is not platform.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentIds" ], "properties": { "agentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Agent IDs to approve" }, "reason": { "type": "string", "maxLength": 1000, "description": "Justification for bulk approval (recorded in audit trail)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "enterpriseId", "required": true } ], "responses": { "200": { "description": "Bulk approval result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnterpriseAgent" } }, "approved": { "type": "integer" } }, "additionalProperties": false, "description": "Bulk approval result." } } } }, "400": { "description": "Too many agents or invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/enterprises/{enterpriseId}/agents": { "get": { "operationId": "listEnterpriseAgents", "summary": "List agents registered with this enterprise", "tags": [ "Enterprise Agents" ], "description": "Returns all agents in the enterprise agent registry, optionally filtered by status.\n\n**Auth:** enterprise (own enterprise) or platform", "parameters": [ { "schema": { "type": "string", "enum": [ "approved", "suspended", "revoked" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by agent status" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Pagination cursor (opaque, from previous response). Overrides offset when provided." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for offset-based pagination. Ignored when cursor is provided." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "enterpriseId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnterpriseAgent" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/enterprises/{enterpriseId}/approval-config": { "get": { "operationId": "getApprovalConfig", "summary": "Get agent approval configuration", "tags": [ "Enterprise Agents" ], "description": "Returns whether this enterprise requires agent approval before agents can receive mandates.\n\n**Auth:** enterprise (own enterprise) or platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "enterpriseId", "required": true } ], "responses": { "200": { "description": "Current approval configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentApprovalRequired": { "type": "boolean", "description": "Whether agents must be explicitly approved before receiving mandates from this enterprise" } }, "required": [ "agentApprovalRequired" ], "additionalProperties": false, "description": "Current approval configuration." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "setApprovalConfig", "summary": "Update agent approval configuration", "tags": [ "Enterprise Agents" ], "description": "Enable or disable the requirement for agents to be explicitly approved before they can receive mandates from this enterprise. When enabled, only agents in the enterprise agent registry with `approved` status can be assigned mandates. Changes are recorded in the system audit trail.\n\n**Auth:** enterprise (own enterprise) or platform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentApprovalRequired" ], "properties": { "agentApprovalRequired": { "type": "boolean", "description": "Set to true to require agent approval, false to allow any agent" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "enterpriseId", "required": true } ], "responses": { "200": { "description": "Approval configuration updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentApprovalRequired": { "type": "boolean", "description": "Whether agents must be explicitly approved before receiving mandates from this enterprise" } }, "required": [ "agentApprovalRequired" ], "additionalProperties": false, "description": "Approval configuration updated." } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mandates/{id}/references": { "post": { "operationId": "addMandateReferences", "summary": "Append references to a mandate", "tags": [ "References" ], "description": "Attach external entity references to a mandate. Append-only — references cannot be modified or deleted. Duplicates (same system + refType + refId) are silently ignored.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "references" ], "properties": { "references": { "type": "array", "items": { "type": "object", "required": [ "system", "refType", "refId" ], "properties": { "system": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$", "description": "External system identifier (lowercase, alphanumeric + dots/hyphens/underscores)" }, "refType": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$", "description": "Reference type within the system (e.g., sales-order, ticket, service-principal)" }, "refId": { "type": "string", "minLength": 1, "maxLength": 500, "description": "External identifier within the system" }, "displayName": { "type": "string", "maxLength": 500, "description": "Human-readable label (snapshot at attachment time, not refreshed)" }, "uri": { "type": "string", "maxLength": 2048, "pattern": "^https?://", "description": "URL back to the source system (https only)" }, "attributes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Flat key-value metadata (max 10 keys, max 4KB total)" } }, "additionalProperties": false }, "minItems": 1, "maxItems": 25, "description": "References to attach (max 25 total per mandate)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "References added.", "content": { "application/json": { "schema": { "description": "References added.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" } }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getMandateReferences", "summary": "List references for a mandate", "tags": [ "References" ], "description": "Returns all external entity references attached to a mandate. References are append-only and cannot be modified or deleted.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{id}/references": { "post": { "operationId": "addAgentReferences", "summary": "Append references to an agent", "tags": [ "References" ], "description": "Attach external identity references to an agent. Append-only. Duplicates silently ignored.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "references" ], "properties": { "references": { "type": "array", "items": { "type": "object", "required": [ "system", "refType", "refId" ], "properties": { "system": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$", "description": "External system identifier (lowercase, alphanumeric + dots/hyphens/underscores)" }, "refType": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$", "description": "Reference type within the system (e.g., sales-order, ticket, service-principal)" }, "refId": { "type": "string", "minLength": 1, "maxLength": 500, "description": "External identifier within the system" }, "displayName": { "type": "string", "maxLength": 500, "description": "Human-readable label (snapshot at attachment time, not refreshed)" }, "uri": { "type": "string", "maxLength": 2048, "pattern": "^https?://", "description": "URL back to the source system (https only)" }, "attributes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Flat key-value metadata (max 10 keys, max 4KB total)" } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10, "description": "References to attach (max 10 total per agent)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "References added.", "content": { "application/json": { "schema": { "description": "References added.", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" } }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "getAgentReferences", "summary": "List references for an agent", "tags": [ "References" ], "description": "Returns all external identity references attached to an agent. References are append-only and cannot be modified or deleted.\n\n**Auth:** enterprise, agent, platform", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" } } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/references": { "get": { "operationId": "lookupReferences", "summary": "Reverse lookup — find entities by external reference", "tags": [ "References" ], "description": "Find all mandates and agents that reference a given external entity. Returns both mandate and agent references.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$" }, "in": "query", "name": "system", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$" }, "in": "query", "name": "refType", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "in": "query", "name": "refId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "mandate", "agent" ] }, "entityId": { "type": "string", "format": "uuid" }, "reference": { "$ref": "#/components/schemas/EntityReference" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{id}": { "get": { "operationId": "getAgent", "summary": "Get agent details", "tags": [ "Agents" ], "description": "Returns agent identity, enrichment fields, and attached references.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "slug": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "verificationMethod": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] }, "agentCardUrl": { "type": [ "null", "string" ] }, "agentClass": { "type": "string", "enum": [ "personal", "system", "team", "ephemeral" ] }, "ownerRef": { "type": [ "null", "string" ] }, "orgUnit": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" } }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateAgentIdentity", "summary": "Update agent identity fields", "tags": [ "Agents" ], "description": "Update agent classification, owner, org unit, or description. Only the agent itself or the enterprise that registered it can update these fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentClass": { "type": "string", "enum": [ "personal", "system", "team", "ephemeral" ], "description": "Agent classification: personal (human-owned), system (always-on), team (shared), ephemeral (per-task)" }, "ownerRef": { "type": [ "string", "null" ], "maxLength": 320, "description": "Owner identity (email or identity URI of responsible person/team)" }, "orgUnit": { "type": [ "string", "null" ], "maxLength": 255, "description": "Organizational unit (department, team, cost center)" }, "description": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Plain-text description of what this agent does" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "slug": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "verificationMethod": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] }, "agentCardUrl": { "type": [ "null", "string" ] }, "agentClass": { "type": "string", "enum": [ "personal", "system", "team", "ephemeral" ] }, "ownerRef": { "type": [ "null", "string" ] }, "orgUnit": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" } }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/enterprises": { "get": { "operationId": "adminListEnterprises", "summary": "List all enterprises", "tags": [ "Admin" ], "description": "Returns a paginated list of all enterprise accounts with mandate counts.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Pagination cursor (opaque, from previous response). Overrides offset when provided." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for offset-based pagination. Ignored when cursor is provided." }, { "schema": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "in": "query", "name": "trustLevel", "required": false }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "search", "required": false, "description": "Search by name (ILIKE)" } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "verificationMethod": { "type": [ "null", "string" ] }, "mandateCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "adminCreateEnterprise", "summary": "Create an enterprise account", "tags": [ "Admin" ], "description": "Creates an enterprise account without generating an API key. Use POST /admin/api-keys to create keys separately.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Enterprise display name" }, "slug": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", "description": "DNS-label-safe identifier for provisioning lookups. Auto-generated from name if omitted. Must be unique." }, "email": { "type": "string", "format": "email", "maxLength": 320, "description": "Contact email for the enterprise" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ], "default": "sandbox", "description": "Initial trust level. Default: sandbox." }, "config": { "type": "object", "additionalProperties": true, "description": "Initial config JSONB (enforcement, approvedSuppliers, etc.)" } }, "additionalProperties": false } } } }, "security": [ { "platformAuth": [] } ], "responses": { "201": { "description": "Enterprise created.", "content": { "application/json": { "schema": { "description": "Enterprise created.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "verificationMethod": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions to complete setup" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Slug already in use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/enterprises/{id}/config": { "get": { "operationId": "adminGetEnterpriseConfig", "summary": "Get enterprise config", "tags": [ "Admin" ], "description": "Returns the enterprise's JSONB config.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Enterprise config.", "content": { "application/json": { "schema": { "description": "Enterprise config.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "config": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Enterprise not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "adminUpdateEnterpriseConfig", "summary": "Update enterprise config", "tags": [ "Admin" ], "description": "Merges the provided fields into the enterprise's JSONB config column. Existing keys not present in the request body are preserved. Set a key to `null` to remove it.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enforcement": { "type": "object", "properties": { "constraintInheritanceDefault": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "maxDelegationDepth": { "type": "integer", "minimum": 1, "maximum": 10 }, "criteriaSizeLimitBytes": { "type": "integer", "minimum": 1024, "maximum": 65536 }, "advisoryMode": { "type": "boolean" }, "toleranceEnforcement": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "deadlineEnforcement": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "schemaValidation": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "maxSubmissionsMode": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "expressionRuleMode": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "allowMandateOverrides": { "type": "boolean" } }, "additionalProperties": false }, "approvedSuppliers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 1000, "description": "List of approved supplier IDs for the supplier_approved verification rule." } }, "additionalProperties": false, "description": "Enterprise config update. Accepts enforcement settings and approvedSuppliers." } } }, "description": "Enterprise config update. Accepts enforcement settings and approvedSuppliers." }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Updated enterprise config.", "content": { "application/json": { "schema": { "description": "Updated enterprise config.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "config": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Enterprise not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "adminReplaceEnterpriseConfig", "summary": "Replace enterprise config", "tags": [ "Admin" ], "description": "Replaces the enterprise's entire JSONB config column with the provided object. Any keys not present in the request body are removed. Use PATCH for merge-update semantics.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enforcement": { "type": "object", "properties": { "constraintInheritanceDefault": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "maxDelegationDepth": { "type": "integer", "minimum": 1, "maximum": 10 }, "criteriaSizeLimitBytes": { "type": "integer", "minimum": 1024, "maximum": 65536 }, "advisoryMode": { "type": "boolean" }, "toleranceEnforcement": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "deadlineEnforcement": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "schemaValidation": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "maxSubmissionsMode": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "expressionRuleMode": { "type": "string", "enum": [ "none", "advisory", "enforced" ] }, "allowMandateOverrides": { "type": "boolean" } }, "additionalProperties": false }, "approvedSuppliers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 1000, "description": "List of approved supplier IDs for the supplier_approved verification rule." } }, "additionalProperties": false, "description": "Complete enterprise config. Replaces existing config entirely." } } }, "description": "Complete enterprise config. Replaces existing config entirely." }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Replaced enterprise config.", "content": { "application/json": { "schema": { "description": "Replaced enterprise config.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "config": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Enterprise not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/agents": { "get": { "operationId": "adminListAgents", "summary": "List all agents", "tags": [ "Admin" ], "description": "Returns a paginated list of all agent accounts with mandate counts.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Pagination cursor (opaque, from previous response). Overrides offset when provided." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for offset-based pagination. Ignored when cursor is provided." }, { "schema": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "in": "query", "name": "trustLevel", "required": false }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "search", "required": false, "description": "Search by display name (ILIKE)" } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "slug": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "verificationMethod": { "type": [ "null", "string" ] }, "agentCardUrl": { "type": [ "null", "string" ] }, "mandateCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "adminCreateAgent", "summary": "Create an agent account", "tags": [ "Admin" ], "description": "Creates an agent account without generating an API key. Use POST /admin/api-keys to create keys separately.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Agent display name" }, "slug": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", "description": "DNS-label-safe identifier for provisioning lookups. Auto-generated from name if omitted. Must be unique." }, "email": { "type": "string", "format": "email", "maxLength": 320, "description": "Contact email for the agent operator" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ], "default": "sandbox", "description": "Initial trust level. Default: sandbox." }, "agentCardUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "URL to the agent's AgentCard for identity verification" } }, "additionalProperties": false } } } }, "security": [ { "platformAuth": [] } ], "responses": { "201": { "description": "Agent created.", "content": { "application/json": { "schema": { "description": "Agent created.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "slug": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "verificationMethod": { "type": [ "null", "string" ] }, "agentCardUrl": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions to complete setup" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Slug already in use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/api-keys": { "get": { "operationId": "adminListApiKeys", "summary": "List API keys for an owner", "tags": [ "Admin" ], "description": "Returns API keys for a specific owner. Never returns key hashes.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "ownerId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "enterprise", "agent", "platform" ] }, "ownerId": { "type": "string", "format": "uuid" }, "ownerType": { "type": "string" }, "label": { "type": [ "null", "string" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "null", "string" ], "format": "date-time" }, "expiresAt": { "type": [ "null", "string" ], "format": "date-time" }, "deactivatesAt": { "type": [ "null", "string" ], "format": "date-time" }, "createdByKeyId": { "type": [ "null", "string" ], "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": [ "null", "array" ], "items": { "type": "string" } }, "allowedIps": { "type": [ "null", "array" ], "items": { "type": "string" } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "adminCreateApiKey", "summary": "Create an API key for any owner", "tags": [ "Admin" ], "description": "Creates a new API key for the specified owner. Returns the plaintext key once — it cannot be retrieved again.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role", "ownerId", "ownerType" ], "properties": { "role": { "type": "string", "enum": [ "enterprise", "agent", "platform" ] }, "ownerId": { "type": "string", "format": "uuid" }, "ownerType": { "type": "string", "enum": [ "enterprise", "agent", "platform" ] }, "label": { "type": "string", "maxLength": 255 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional expiration timestamp" }, "environment": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Explicit scopes for the key. If omitted, defaults to role-appropriate scope profile (agent-full for agents, standard for enterprises)." }, "scopeProfile": { "type": "string", "enum": [ "sidecar", "dashboard", "standard", "iac-pipeline", "schema-manager", "agent-full", "agent-readonly" ], "description": "Convenience preset — expands to a predefined scope array. Takes precedence over scopes." }, "allowedIps": { "type": "array", "items": { "type": "string" }, "description": "IP allowlist. Requests from IPs not in this list will be rejected with 403." } }, "additionalProperties": false } } } }, "security": [ { "platformAuth": [] } ], "responses": { "201": { "description": "API key created. The apiKey field is shown once — store it securely.", "content": { "application/json": { "schema": { "description": "API key created. The apiKey field is shown once — store it securely.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "apiKey": { "type": "string", "description": "Plaintext API key (shown once)" }, "role": { "type": "string" }, "ownerId": { "type": "string", "format": "uuid" }, "label": { "type": [ "null", "string" ] }, "expiresAt": { "type": [ "null", "string" ], "format": "date-time" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": [ "null", "array" ], "items": { "type": "string" } }, "scopeProfile": { "type": [ "null", "string" ] }, "allowedIps": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "IP allowlist applied to this key. null = any IP allowed." }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions after creating the key" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Maximum active keys per owner exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/accounts/{id}/trust-level": { "patch": { "operationId": "adminSetTrustLevel", "summary": "Set account trust level", "tags": [ "Admin" ], "description": "Admin-only trust level change (can upgrade or downgrade). Logged to audit vault.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trustLevel", "accountType" ], "properties": { "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "accountType": { "type": "string", "enum": [ "enterprise", "agent" ] }, "reason": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Trust level updated.", "content": { "application/json": { "schema": { "description": "Trust level updated.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountType": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "previousTrustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions in the onboarding flow" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/accounts/{id}/deactivate": { "post": { "operationId": "adminDeactivateAccount", "summary": "Deactivate an account", "tags": [ "Admin" ], "description": "Soft-deactivates an account: downgrades trust level to sandbox, bulk-revokes all active API keys, and records the action in system_audit_log. Does NOT delete data.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accountType" ], "properties": { "accountType": { "type": "string", "enum": [ "enterprise", "agent" ] }, "reason": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Account deactivated.", "content": { "application/json": { "schema": { "description": "Account deactivated.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountType": { "type": "string" }, "previousTrustLevel": { "type": "string", "enum": [ "sandbox", "active", "verified" ] }, "keysRevoked": { "type": "integer", "description": "Number of API keys deactivated" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/webhook-dlq": { "get": { "operationId": "adminListDlq", "summary": "List webhook dead letter queue", "tags": [ "Admin" ], "description": "Returns failed webhook deliveries from the DLQ.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Pagination cursor (opaque, from previous response). Overrides offset when provided." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for offset-based pagination. Ignored when cursor is provided." } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subscriptionId": { "type": "string", "format": "uuid" }, "subscriptionUrl": { "type": [ "null", "string" ] }, "eventId": { "type": "string", "format": "uuid" }, "eventType": { "type": "string" }, "errorMessage": { "type": "string" }, "attempts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/system-health": { "get": { "operationId": "adminSystemHealth", "summary": "System health overview", "tags": [ "Admin" ], "description": "Returns service health indicators including database connectivity and latency, queue depths, connection pool stats, and process memory usage.\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "System health status.", "content": { "application/json": { "schema": { "description": "System health status.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded" ] }, "uptime": { "type": "number", "description": "Process uptime in seconds" }, "database": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded" ] }, "latencyMs": { "type": [ "null", "number" ], "description": "SELECT 1 round-trip latency in ms" }, "pool": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total connections in pool" }, "idle": { "type": "integer", "description": "Idle connections available" }, "waiting": { "type": "integer", "description": "Queued connection requests" } }, "additionalProperties": false } }, "additionalProperties": false }, "queues": { "type": "object", "additionalProperties": { "type": "object", "properties": { "waiting": { "type": "integer" }, "active": { "type": "integer" }, "delayed": { "type": "integer" }, "failed": { "type": "integer" } }, "additionalProperties": false }, "description": "Job counts per queue (pg-boss)" }, "process": { "type": "object", "properties": { "rssMb": { "type": "number", "description": "Resident set size in MB" }, "heapUsedMb": { "type": "number", "description": "V8 heap used in MB" }, "heapTotalMb": { "type": "number", "description": "V8 heap total in MB" } }, "additionalProperties": false }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/webhook-dlq/{dlqId}/retry": { "post": { "operationId": "adminRetryDlq", "summary": "Retry a DLQ entry", "tags": [ "Admin" ], "description": "Re-enqueues a failed webhook delivery for retry and removes it from the DLQ.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "dlqId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "DLQ entry retried successfully.", "content": { "application/json": { "schema": { "description": "DLQ entry retried successfully.", "type": "object", "properties": { "success": { "type": "boolean" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "DLQ entry not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/webhook-dlq/retry-all": { "post": { "operationId": "adminRetryAllDlq", "summary": "Retry all DLQ entries", "tags": [ "Admin" ], "description": "Re-enqueues up to 100 failed webhook deliveries for retry.\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Bulk retry result.", "content": { "application/json": { "schema": { "description": "Bulk retry result.", "type": "object", "properties": { "retried": { "type": "integer", "description": "Number of entries successfully retried" }, "failed": { "type": "integer", "description": "Number of entries that failed to retry" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/api-keys/bulk-revoke": { "post": { "operationId": "adminBulkRevokeKeys", "summary": "Bulk revoke API keys", "tags": [ "Admin" ], "description": "Deactivates API keys matching the specified filters. At least one filter is required.\nAccepts key IDs (max 100) and/or filter criteria (ownerId, role, createdBefore).\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100, "description": "Specific key IDs to revoke (max 100)" }, "ownerId": { "type": "string", "format": "uuid", "description": "Revoke all keys for this owner" }, "role": { "type": "string", "enum": [ "enterprise", "agent", "platform" ], "description": "Revoke all keys with this role" }, "createdBefore": { "type": "string", "format": "date-time", "description": "Revoke keys created before this timestamp" }, "reason": { "type": "string", "maxLength": 500, "description": "Reason for revocation (audit trail)" } }, "additionalProperties": false } } } }, "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Bulk revocation result.", "content": { "application/json": { "schema": { "description": "Bulk revocation result.", "type": "object", "properties": { "revoked": { "type": "integer", "description": "Number of keys deactivated" }, "alreadyInactive": { "type": "integer", "description": "Number of keys that were already inactive" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/api-keys/{keyId}": { "patch": { "operationId": "adminToggleApiKey", "summary": "Update API key status or scopes", "tags": [ "Admin" ], "description": "Enable/disable an API key or update its scopes. Cannot disable the last active platform key.\n\nTo update scopes, provide a `scopes` array of valid scope strings or a `scopeProfile` name. Scope escalation rules apply: the caller's key must have all scopes being granted.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isActive": { "type": "boolean" }, "reason": { "type": "string", "maxLength": 500 }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "New scope set for the key. Scope escalation rules apply." }, "scopeProfile": { "type": "string", "enum": [ "sidecar", "dashboard", "standard", "iac-pipeline", "schema-manager", "agent-full", "agent-readonly" ], "description": "Scope profile name. Resolved to scopes." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "keyId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "API key updated.", "content": { "application/json": { "schema": { "description": "API key updated.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "isActive": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "scopeProfile": { "type": "string", "nullable": true } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "API key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/agents/{agentId}/capabilities": { "put": { "operationId": "adminSetAgentCapabilities", "summary": "Set agent capabilities (admin)", "tags": [ "Admin" ], "description": "Admin override to set the accepted contract types for any agent.\n\n**Auth:** platform role only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contractTypes" ], "properties": { "contractTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 100, "description": "Contract types the agent accepts." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "agentId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Updated agent capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "contractType": { "type": "string" }, "declaredAt": { "type": "string", "format": "date-time" }, "reputation": { "type": [ "null", "object" ], "properties": { "compositeScore": { "type": [ "null", "number" ] }, "confidenceLevel": { "type": [ "null", "number" ] }, "totalMandates": { "type": "integer" }, "totalPassed": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false, "description": "Updated agent capabilities." } } } }, "400": { "description": "Invalid contract type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/agents/capabilities": { "get": { "operationId": "adminGetFleetCapabilities", "summary": "Get fleet capability overview", "tags": [ "Admin" ], "description": "Returns all agents that have declared capabilities, with optional contract type filter.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "in": "query", "name": "contractType", "required": false, "description": "Filter agents by accepted contract type" } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Fleet capabilities.", "content": { "application/json": { "schema": { "description": "Fleet capabilities.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "null", "string" ] }, "contractTypes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "null", "string" ] } }, "additionalProperties": false } } } }, "400": { "description": "Invalid contract type filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/rate-limit-exemptions/{ownerId}": { "put": { "operationId": "adminAddRateLimitExemption", "summary": "Add rate-limit exemption for an owner", "tags": [ "Admin" ], "description": "Adds an owner ID to the runtime rate-limit exemption set (100k req/min). Persists until process restart. Use RATE_LIMIT_EXEMPT_OWNERS env var for permanent exemptions.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "ownerId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Exemption added.", "content": { "application/json": { "schema": { "description": "Exemption added.", "type": "object", "properties": { "ownerId": { "type": "string", "format": "uuid" }, "exempt": { "type": "boolean" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "adminRemoveRateLimitExemption", "summary": "Remove rate-limit exemption for an owner", "tags": [ "Admin" ], "description": "Removes an owner ID from the runtime rate-limit exemption set.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "ownerId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Exemption removed (or was not present).", "content": { "application/json": { "schema": { "description": "Exemption removed (or was not present).", "type": "object", "properties": { "ownerId": { "type": "string", "format": "uuid" }, "exempt": { "type": "boolean" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/rate-limit-exemptions": { "get": { "operationId": "adminListRateLimitExemptions", "summary": "List rate-limit exempt owners", "tags": [ "Admin" ], "description": "Returns all owner IDs currently exempt from rate limiting (env var + runtime additions).\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "List of exempt owner IDs.", "content": { "application/json": { "schema": { "description": "List of exempt owner IDs.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "null", "string" ] } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/rate-limit-exemptions/ip/{ip}": { "put": { "operationId": "adminAddIpRateLimitExemption", "summary": "Add IP-based rate-limit exemption", "tags": [ "Admin" ], "description": "Exempt an IP address from rate limits. Covers unauthenticated routes (portal signup/login). Use for test environments. In-memory only — resets on process restart.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-fA-F.:]+$", "minLength": 1, "maxLength": 45 }, "in": "path", "name": "ip", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string" }, "exempt": { "type": "boolean" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "adminRemoveIpRateLimitExemption", "summary": "Remove IP-based rate-limit exemption", "tags": [ "Admin" ], "description": "Remove an IP address from the rate-limit exemption list.\n\n**Auth:** platform (admin:system scope)", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-fA-F.:]+$", "minLength": 1, "maxLength": 45 }, "in": "path", "name": "ip", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string" }, "exempt": { "type": "boolean" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/rate-limit-exemptions/ips": { "get": { "operationId": "adminListIpRateLimitExemptions", "summary": "List IP-based rate-limit exemptions", "tags": [ "Admin" ], "description": "Returns all IP addresses currently exempt from rate limits.\n\n**Auth:** platform (admin:system scope)", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/auth-cache/flush": { "post": { "operationId": "adminFlushAuthCache", "summary": "Flush auth cache", "tags": [ "Admin" ], "description": "Clears all entries from the auth LRU cache. Subsequent requests will query the database.\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Cache flushed successfully.", "content": { "application/json": { "schema": { "description": "Cache flushed successfully.", "type": "object", "properties": { "flushed": { "type": "boolean" } }, "required": [ "flushed" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/auth-cache/stats": { "get": { "operationId": "adminAuthCacheStats", "summary": "Auth cache statistics", "tags": [ "Admin" ], "description": "Returns current auth LRU cache size, max capacity, and TTL.\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Cache statistics.", "content": { "application/json": { "schema": { "description": "Cache statistics.", "type": "object", "properties": { "size": { "type": "integer", "description": "Current number of entries in cache" }, "max": { "type": "integer", "description": "Maximum cache capacity" }, "ttl": { "type": "integer", "description": "TTL in milliseconds" } }, "required": [ "size", "max", "ttl" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/license": { "get": { "operationId": "adminGetLicense", "summary": "License status", "tags": [ "Admin" ], "description": "Returns current license validation status, tier, expiry, and entitlements.\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Current license status.", "content": { "application/json": { "schema": { "description": "Current license status.", "type": "object", "properties": { "validity": { "type": "string", "enum": [ "valid", "unlicensed", "lapsed", "invalid_signature", "invalid_format", "instance_mismatch", "version_too_new" ] }, "tier": { "type": "string", "enum": [ "free", "enterprise" ] }, "features": { "type": "array", "items": { "type": "string" } }, "customerId": { "type": [ "null", "string" ] }, "customerName": { "type": [ "null", "string" ] }, "instanceId": { "type": [ "null", "string" ], "format": "uuid" }, "licensedThrough": { "type": [ "null", "string" ], "format": "date" }, "releaseDate": { "type": "string", "format": "date" }, "licenseId": { "type": [ "null", "string" ], "format": "uuid" }, "checkedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "nextSteps": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "validity", "tier", "features", "checkedAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/license/instance-id": { "get": { "operationId": "adminGetInstanceId", "summary": "Database instance ID", "tags": [ "Admin" ], "description": "Returns the database instance_id used for license binding. Customer copies this to send to sales or enter in the activation portal.\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "instanceId": { "type": "string", "format": "uuid" }, "nextSteps": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "instanceId" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/license/reload": { "post": { "operationId": "adminReloadLicense", "summary": "Reload license", "tags": [ "Admin" ], "description": "Re-reads the license from AGLEDGER_LICENSE_KEY / AGLEDGER_LICENSE_KEY_FILE, re-validates, and updates the server license status. Use after K8s secret rotation without restarting.\n\n**Auth:** platform role only.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "validity": { "type": "string", "enum": [ "valid", "unlicensed", "lapsed", "invalid_signature", "invalid_format", "instance_mismatch", "version_too_new" ] }, "tier": { "type": "string", "enum": [ "free", "enterprise" ] }, "features": { "type": "array", "items": { "type": "string" } }, "customerId": { "type": [ "null", "string" ] }, "customerName": { "type": [ "null", "string" ] }, "instanceId": { "type": [ "null", "string" ], "format": "uuid" }, "licensedThrough": { "type": [ "null", "string" ], "format": "date" }, "releaseDate": { "type": "string", "format": "date" }, "licenseId": { "type": [ "null", "string" ], "format": "uuid" }, "checkedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "nextSteps": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "validity", "tier", "features", "checkedAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/mandates": { "get": { "operationId": "adminListMandates", "summary": "List mandates cross-enterprise", "tags": [ "Admin" ], "description": "Returns a paginated list of mandates across all enterprises. Supports filtering by enterprise, status, contract type, agent, and date range.\n\n**Auth:** platform role only.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for cursor-based pagination (overrides offset when provided). Returned as nextCursor in previous response." }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "enterpriseId", "required": false, "description": "Filter by enterprise ID" }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Filter by mandate status" }, { "schema": { "type": "string" }, "in": "query", "name": "contractType", "required": false, "description": "Filter by contract type" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "agentId", "required": false, "description": "Filter by performer agent ID" }, { "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" }, "in": "query", "name": "sort", "required": false }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "order", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Filter: created after" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "Filter: created before" } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterpriseId": { "type": [ "null", "string" ], "format": "uuid" }, "agentId": { "type": [ "null", "string" ], "format": "uuid" }, "principalType": { "type": "string", "enum": [ "enterprise", "agent" ] }, "principalAgentId": { "type": [ "null", "string" ], "format": "uuid" }, "contractType": { "type": "string" }, "status": { "type": "string" }, "operatingMode": { "type": "string", "enum": [ "cleartext", "encrypted" ] }, "verificationMode": { "type": "string", "enum": [ "auto", "principal", "gated" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextCursor": { "type": [ "null", "string" ] }, "hasMore": { "type": "boolean" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/webhooks/health": { "get": { "operationId": "adminGetWebhooksHealth", "summary": "Webhook subscription health overview", "tags": [ "Admin" ], "description": "Lists all active webhook subscriptions with circuit breaker state, sorted by failure count.\n\n**Auth:** platform (admin:system scope)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "ownerId": { "type": "string", "format": "uuid" }, "ownerType": { "type": "string" }, "isActive": { "type": "boolean" }, "isPaused": { "type": "boolean" }, "circuitState": { "type": "string", "enum": [ "closed", "open", "half_open" ] }, "consecutiveFailures": { "type": "integer" }, "lastSuccessfulAt": { "type": "string", "format": "date-time", "nullable": true }, "circuitOpenedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/webhooks/{webhookId}/circuit-breaker": { "patch": { "operationId": "adminOverrideWebhookCircuitBreaker", "summary": "Override webhook circuit breaker state", "tags": [ "Admin" ], "description": "Manually set the circuit breaker state for a subscription. Setting to \"closed\" resets consecutive failures.\n\n**Auth:** platform (admin:system scope)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "closed", "open", "half_open" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "webhookId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "circuitState": { "type": "string" }, "consecutiveFailures": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/vault/signing-keys": { "get": { "operationId": "adminListVaultSigningKeys", "summary": "List vault signing keys", "tags": [ "Admin" ], "description": "Returns all vault signing keys in the registry with their lifecycle status.\n\n**Auth:** platform role with `admin:system` scope.", "security": [ { "platformAuth": [] } ], "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)" }, "algorithm": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retired" ] }, "activatedAt": { "type": "string", "format": "date-time" }, "retiredAt": { "type": [ "null", "string" ], "format": "date-time" } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/vault/signing-keys/rotate": { "post": { "operationId": "adminRotateVaultSigningKey", "summary": "Rotate vault signing key", "tags": [ "Admin" ], "description": "Activates the current VAULT_SIGNING_KEY env var as the new active key and retires the previous one. The operator must update the env var before calling this endpoint.\n\n**Auth:** platform role with `admin:system` scope.", "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "previousKeyId": { "type": [ "null", "string" ] }, "newKeyId": { "type": "string" }, "status": { "type": "string", "enum": [ "rotated", "already_active" ] }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/vault/anchors": { "get": { "operationId": "adminListVaultAnchors", "summary": "List anchored checkpoints for a mandate", "tags": [ "Admin" ], "description": "Lists S3-anchored vault checkpoints for a given mandate. Requires vault anchoring to be enabled.\n\n**Auth:** platform role with `admin:system` scope.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "mandateId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "lastModified": { "type": [ "null", "string" ], "format": "date-time" }, "size": { "type": [ "null", "integer" ] } }, "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" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/vault/anchors/verify": { "post": { "operationId": "adminVerifyVaultAnchors", "summary": "Verify vault checkpoint anchors", "tags": [ "Admin" ], "description": "Compares DB checkpoints against their S3 anchors for a given mandate. Detects tampering if the DB checkpoint has been modified after anchoring.\n\n**Auth:** platform role with `admin:system` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mandateId" ], "properties": { "mandateId": { "type": "string", "format": "uuid" }, "chainPosition": { "type": "integer", "description": "Specific chain position to verify (omit for latest 10)" } }, "additionalProperties": false } } } }, "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "mandateId": { "type": "string", "format": "uuid" }, "chainPosition": { "type": "integer" }, "match": { "type": "boolean" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mandate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/vault/scan": { "post": { "operationId": "adminStartVaultScan", "summary": "Start a full vault integrity scan", "tags": [ "Admin" ], "description": "Enqueues a background job that verifies every vault chain in the database. Returns a job ID for status polling. Use after DB restores or incident response.\n\n**Auth:** platform role with `admin:system` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mandateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 1000, "description": "Optional list of mandate IDs to scan. Omit to scan all mandates." } }, "additionalProperties": false } } } }, "security": [ { "platformAuth": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/vault/scan/{jobId}": { "get": { "operationId": "adminGetVaultScanStatus", "summary": "Get vault integrity scan status", "tags": [ "Admin" ], "description": "Polls the status of a vault integrity scan job.\n\n**Auth:** platform role with `admin:system` scope.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "jobId", "required": true } ], "security": [ { "platformAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "state" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "created", "active", "completed", "failed", "expired" ] }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "result": { "type": "object", "nullable": true, "properties": { "total": { "type": "integer" }, "verified": { "type": "integer" }, "broken": { "type": "integer" }, "signatureErrors": { "type": "integer" }, "brokenMandates": { "type": "array", "items": { "type": "object", "properties": { "mandateId": { "type": "string", "format": "uuid" }, "brokenAt": { "type": "integer" } } } }, "errors": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStepAction" }, "description": "Suggested next actions for AI agents and automation workflows" } }, "additionalProperties": false } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/audit/stream": { "get": { "operationId": "getAuditStream", "summary": "Pull audit events as OCSF NDJSON", "tags": [ "Audit" ], "description": "Returns audit events in OCSF v1.4.0 format as NDJSON. Designed for SIEM ingestion (Splunk, Sentinel, QRadar, CrowdStrike, Elastic). Use `X-AGLedger-Stream-Cursor` response header for efficient polling. Results are scoped by role: enterprises see events for their own mandates, agents see mandates where they are performer or principal, platform sees everything.\n\n**Auth:** enterprise, agent, platform\n**Scope:** `audit:read`", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "since", "required": true, "description": "Return events created after this timestamp (required)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum events to return" }, { "schema": { "type": "string", "enum": [ "ocsf", "raw" ], "default": "ocsf" }, "in": "query", "name": "format", "required": false, "description": "Output format: ocsf (OCSF v1.4.0) or raw (AGLedger native)" } ], "responses": { "200": { "description": "NDJSON stream of audit events. Each line is a self-contained JSON object.", "content": { "application/json": { "schema": { "description": "NDJSON stream of audit events. Each line is a self-contained JSON object.", "type": "string" } } } }, "401": { "description": "Unauthorized -- missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden -- authenticated but insufficient permissions for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. This is temporary — retry the same request after retryAfterSeconds. Sandbox: 200 req/min. Agents: 500 req/min. Enterprise (and their agents): 1,000 req/min.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "servers": [ { "url": "/v1", "description": "AGLedger API (v1)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Auth", "description": "Self-service account registration and verification. Create an enterprise or agent account and receive a one-time API key. New accounts start in sandbox mode with restricted access (max 5 mandates, no webhooks, reduced rate limits). Three verification paths to unlock full access: (1) email verification via link, (2) A2A AgentCard verification for agents, (3) auto-graduation after first successful mandate verification. Registration is rate limited to 5/15min per IP with a global ceiling of 100/hour." }, { "name": "Health", "description": "Service health check. No authentication required." }, { "name": "Schemas", "description": "Contract type schema registry (public, no authentication required). Lists available contract types and returns the JSON Schema definitions for mandate criteria and receipt evidence. Use the validation endpoint to dry-run receipt evidence against a contract type before submitting.\n\n**9 contract types available:**\n- `ACH-PROC-v1` — Procurement (purchase orders, supplier verification)\n- `ACH-DLVR-v1` — Deliverables (work products, documents, code)\n- `ACH-DATA-v1` — Data Processing (ETL, format validation)\n- `ACH-TXN-v1` — Transactions (financial, confirmations)\n- `ACH-ORCH-v1` — Orchestration (delegation, coordination)\n- `ACH-COMM-v1` — Communication (email, chat, webhooks, tickets)\n- `ACH-AUTH-v1` — Authorization (credentials, permissions)\n- `ACH-INFRA-v1` — Infrastructure (DDL, deployments, config)\n- `ACH-DEL-v1` — Destructive Operations (deletions, cancellations, refunds)" }, { "name": "Mandates", "description": "Mandate lifecycle management: create, read, update, search, and state transitions. Mandates progress through an 11-state customer-facing lifecycle: CREATED → ACTIVE → PROCESSING → FULFILLED / FAILED / REVISION_REQUESTED → REMEDIATED. Additional states: PROPOSED and REJECTED (agent-to-agent negotiation), EXPIRED, and CANCELLED. Only mandates in CREATED status can be edited. Supports bulk creation (up to 100), agent-to-agent mandates (bilateral, proposal negotiation, delegation chains), and two operating modes: cleartext (full server verification) and encrypted (self-verification via `/mandates/:id/outcome`). Enterprise users can only access their own mandates; agents can access mandates where they are the performer or principal." }, { "name": "Receipts", "description": "Task attestation submission and retrieval. Agents submit receipt evidence against active mandates. In cleartext mode, Phase 1 structural validation (JSON Schema conformance) runs synchronously and Phase 2 semantic verification (field-by-field checks with tolerance bands) runs asynchronously via pg-boss with results delivered via webhook. In encrypted mode, receipts skip structural validation entirely — the principal self-verifies and reports the outcome via the `/mandates/:id/outcome` endpoint." }, { "name": "Webhooks", "description": "Webhook subscription management and delivery logs. Register HTTPS endpoints to receive real-time event notifications. Webhook secrets are generated server-side and returned once on creation -- store them securely. Payloads are signed with HMAC-SHA256 (header: `X-AGLedger-Signature: t=,v1=`, signed payload: `${timestamp}.${rawBody}`, replay window: 300s). Each delivery includes an `X-AGLedger-Delivery` UUID header for idempotency. Delivery retries follow exponential backoff: 1s, 5s, 30s, 5m, 30m, 2h, then dead-letter queue. A 410 response auto-disables the subscription. URLs are validated against SSRF (blocks RFC 1918, link-local, loopback, and AWS metadata IPs)." }, { "name": "Events", "description": "Event reconciliation endpoint. Poll to catch events that may have been missed by webhooks. Enterprise users only see events for their own mandates. Supports filtering by timestamp, mandate ID, and event type." }, { "name": "Disputes", "description": "Three-tier dispute resolution system. Tier 1 performs automatic re-adjudication with expanded tolerance bands. If unresolved, disputes can be escalated to Tier 2 (manual review) and Tier 3 (binding arbitration with flat fee). Evidence can be submitted during the evidence window. Dispute outcomes feed back into the mandate lifecycle and agent reputation scores." }, { "name": "Reputation", "description": "Agentic Reputation -- the \"credit bureau for agentic operations.\" Provides composite reputation scores across reliability, accuracy, and efficiency dimensions, with confidence intervals that tighten as transaction volume grows. Scores are broken down per contract type and auto-recalculated on verification and dispute events." }, { "name": "Dashboard", "description": "Enterprise analytics: dashboard statistics (mandate counts by status, verification pass rate, dispute rate, active agent count) and tamper-evident audit trail for individual mandates." }, { "name": "A2A Protocol", "description": "Agent-to-Agent (A2A) protocol endpoints (Linux Foundation open standard). The AgentCard at `/.well-known/agent-card.json` (canonical) and `/.well-known/agent.json` (alias) enables standard A2A discovery. The `/a2a` endpoint accepts JSON-RPC 2.0 requests (`message/send`, `tasks/get`, `tasks/cancel`) that map to AGLedger mandates and receipts. A2A Tasks correspond to mandates; A2A Artifacts correspond to receipts." }, { "name": "Compliance", "description": "EU AI Act deployer compliance record-keeping. Append-only attestation records for workplace notification (Art. 26(7)), affected persons notification (Art. 26(11)), input data quality review (Art. 26(4)), and fundamental rights impact assessment (Art. 27). Also provides structured audit exports in JSON, CSV, and NDJSON formats with chain integrity verification and Ed25519 signature data." }, { "name": "Agent-to-Agent", "description": "Agent-to-agent mandate lifecycle: bilateral mandates, propose/accept/reject negotiation, delegation chains with cascading verification, and commission tracking. Supports three tiers: Tier 1 (direct bilateral), Tier 2 (proposal negotiation), and Tier 3 (delegation chains up to depth 5 with automatic cascading verification). All agent-to-agent endpoints require an agent-role API key." }, { "name": "Proxy", "description": "Governance Sidecar ingestion. Enterprises and agents register proxy sessions and batch-ingest tool call observations, sidecar mandates, and sidecar receipts from the Governance Sidecar (MCP proxy). Sidecar mandates can be formalized into real mandates or dismissed. All data is separation-ready (no foreign keys to core tables) for future service extraction." }, { "name": "Federation", "description": "Instance-to-instance federation (Hub mode). Gateways register with a Hub using RFC 9421 proof-of-possession, then sync state transitions, settlement signals, and agent directories via short-lived bearer tokens. Admin endpoints (registration tokens, gateway management, audit log) require platform role. Registration and self-revocation use token/secret-based auth (no bearer token)." }, { "name": "Federation Admin", "description": "Federation administration (platform role required). Manage Gateway registrations, view federation mandates, query the federation audit log, and manage the outbound dead letter queue." }, { "name": "Admin", "description": "Platform administration endpoints. List and manage enterprises, agents, and API keys. View webhook dead letter queue and system health. All endpoints require platform role." } ] }