{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Ledgero Control Plane API", "description": "Tenant-scoped provisioning and administration.", "version": "1.0.0" }, "components": { "securitySchemes": { "tenantServiceCredential": { "type": "http", "scheme": "bearer", "description": "Tenant service credential; the verified credential supplies tenantId." }, "operatorCapability": { "type": "apiKey", "in": "header", "name": "Ledgero-Operator-Capability", "description": "Tenant-signed ledgero-control JWT with one exact capability." } } }, "paths": { "/v1/administrative/{kind}": { "get": { "operationId": "listAdministrativeResources", "summary": "List one kind of tenant-owned administrative resource", "description": "Tenant and Environment are derived exclusively from the service credential. Results use deterministic seek ordering: updatedAt descending, then resourceId ascending. Inventory is a retained point-in-time observation, never command authority; usage_projection rows are estimates and never billing records.", "tags": [ "Administrative reads" ], "security": [ { "tenantServiceCredential": [] } ], "responses": { "200": { "description": "One bounded page from the Control Plane D1 inventory.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "source": { "type": "string", "const": "control-plane-d1" }, "capturedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "order": { "type": "string", "const": "updatedAt:desc,resourceId:asc" }, "items": { "maxItems": 100, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "auction" }, "auctionId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "state": { "type": "string", "enum": [ "active", "closed" ] } }, "required": [ "resourceId", "updatedAt", "kind", "auctionId", "state" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "lot" }, "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "auctionId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "externalLotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "state": { "type": "string", "enum": [ "scheduled", "provisioning", "provisioned", "open", "paused", "quarantined", "sealing", "sealed", "attention" ] } }, "required": [ "resourceId", "updatedAt", "kind", "lotId", "auctionId", "externalLotId", "state" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "service_credential" }, "credentialId": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "status": { "type": "string", "enum": [ "active", "overlap", "revoked", "expired" ] }, "scopes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "notAfter": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "resourceId", "updatedAt", "kind", "credentialId", "status", "scopes", "createdAt", "notAfter" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "issuer" }, "issuerId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "issuer": { "type": "string", "maxLength": 512, "format": "uri" }, "status": { "type": "string", "enum": [ "active", "disabled", "attention" ] } }, "required": [ "resourceId", "updatedAt", "kind", "issuerId", "issuer", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "webhook_endpoint" }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "endpointOrigin": { "type": "string", "maxLength": 512, "format": "uri" }, "status": { "type": "string", "enum": [ "pending", "active", "disabled", "attention" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "resourceId", "updatedAt", "kind", "endpointId", "endpointOrigin", "status", "revision" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "delivery_attention" }, "attentionId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" } }, "required": [ "resourceId", "updatedAt", "kind", "attentionId", "lotId", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "intervention" }, "interventionId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "commandType": { "type": "string", "enum": [ "pause", "resume", "extend", "amend_increments", "cancel", "quarantine", "seal_quarantined", "restore" ] }, "outcome": { "type": "string", "enum": [ "accepted", "rejected", "attention" ] } }, "required": [ "resourceId", "updatedAt", "kind", "interventionId", "lotId", "commandType", "outcome" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "evidence" }, "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "terminalRecordSequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "terminalSealDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } }, "required": [ "resourceId", "updatedAt", "kind", "lotId", "terminalRecordSequence", "terminalSealDigest" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "ceiling" }, "maxConcurrentOpenLots": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxLotsPerUtcDay": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "resourceId", "updatedAt", "kind", "maxConcurrentOpenLots", "maxLotsPerUtcDay" ], "additionalProperties": false }, { "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "usage_projection" }, "usageDay": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "computedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "final": { "type": "boolean" }, "commandsAccepted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "commandsRejected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionMinutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deliveryAttempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "archiveBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "resourceId", "updatedAt", "kind", "usageDay", "revision", "computedAt", "final", "commandsAccepted", "commandsRejected", "sessionMinutes", "deliveryAttempts", "archiveBytes" ], "additionalProperties": false } ] } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 16, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "administrativeReadVersion", "correlationId", "source", "capturedAt", "order", "items", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid kind, limit or cursor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "401": { "description": "Invalid or inactive service credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "403": { "description": "Missing administrative:read scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "429": { "description": "Administrative read admission was rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "503": { "description": "Administrative inventory is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } } }, "parameters": [ { "in": "path", "name": "kind", "schema": { "type": "string", "enum": [ "auction", "lot", "service_credential", "issuer", "webhook_endpoint", "delivery_attention", "intervention", "evidence", "ceiling", "usage_projection" ] }, "required": true }, { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "minLength": 16, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } } ] } }, "/v1/lots/{lotId}/snapshot": { "get": { "operationId": "getLotAdministrativeSnapshot", "summary": "Read a sanitized authoritative LotActor snapshot", "description": "Tenant and Environment are derived exclusively from the service credential. Successful responses come from the addressed LotActor and never from a cache.", "tags": [ "Administrative reads" ], "security": [ { "tenantServiceCredential": [] } ], "responses": { "200": { "description": "Sanitized point-in-time state read directly from the LotActor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "source": { "type": "string", "const": "lot-actor" }, "freshness": { "type": "string", "const": "authoritative" }, "capturedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "auctionId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "lotState": { "type": "string", "enum": [ "provisioned", "open", "paused", "quarantined", "sealing", "sealed" ] }, "terminalOutcome": { "anyOf": [ { "type": "string", "enum": [ "awarded", "no_award", "cancelled" ] }, { "type": "null" } ] }, "effectiveClosesAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recordSequence": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "market": { "type": "object", "properties": { "currentPrice": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minimumBid": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "incrementStep": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "bidCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reserveMet": { "type": "boolean" }, "reservePrice": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "currentPrice", "minimumBid", "incrementStep" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "correlationId", "source", "freshness", "capturedAt", "tenantId", "auctionId", "lotId", "lotState", "terminalOutcome", "effectiveClosesAt", "recordSequence", "market" ], "additionalProperties": false } } } }, "400": { "description": "Invalid lot id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "401": { "description": "Invalid or inactive service credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "403": { "description": "Missing lot:snapshot:read scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "404": { "description": "Lot is absent, inaccessible or belongs to another tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "429": { "description": "Lot snapshot admission was rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } }, "503": { "description": "The authoritative LotActor snapshot is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "administrativeReadVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "rate_limited", "read_unavailable", "snapshot_unavailable" ] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "retryable": { "type": "boolean" } }, "required": [ "code", "correlationId", "retryable" ], "additionalProperties": false } }, "required": [ "administrativeReadVersion", "error" ], "additionalProperties": false } } } } }, "parameters": [ { "in": "path", "name": "lotId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ] } }, "/v1/service-credentials": { "post": { "operationId": "createServiceCredential", "summary": "Create one narrowed tenant service credential", "tags": [ "Service credentials" ], "security": [ { "tenantServiceCredential": [], "operatorCapability": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceCredentialSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "scopes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "delegableScopes": { "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } } }, "required": [ "serviceCredentialSchemaVersion", "commandId", "scopes", "delegableScopes" ], "additionalProperties": false } } }, "required": true }, "responses": { "201": { "description": "Credential issued once; the response must not be cached.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "serviceCredentialSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "credentialId": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "credential": { "type": "string", "maxLength": 96, "pattern": "^ldg_svc_v1\\.[a-z0-9-]{1,16}\\.[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}$" }, "scopes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "delegableScopes": { "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "operation": { "type": "string", "const": "create" }, "predecessorCredentialId": { "type": "null" }, "predecessorNotAfter": { "type": "null" } }, "required": [ "serviceCredentialSchemaVersion", "commandId", "credentialId", "credential", "scopes", "delegableScopes", "createdAt", "operation", "predecessorCredentialId", "predecessorNotAfter" ], "additionalProperties": false }, { "type": "object", "properties": { "serviceCredentialSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "credentialId": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "credential": { "type": "string", "maxLength": 96, "pattern": "^ldg_svc_v1\\.[a-z0-9-]{1,16}\\.[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}$" }, "scopes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "delegableScopes": { "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "operation": { "type": "string", "const": "rotate" }, "predecessorCredentialId": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "predecessorNotAfter": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "serviceCredentialSchemaVersion", "commandId", "credentialId", "credential", "scopes", "delegableScopes", "createdAt", "operation", "predecessorCredentialId", "predecessorNotAfter" ], "additionalProperties": false } ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid or inactive service credential." }, "403": { "description": "Missing dual authority or requested scope exceeds the caller ceiling." }, "409": { "description": "Command id was already consumed." }, "503": { "description": "Credential lifecycle storage or verifier key is unavailable." } } } }, "/v1/service-credentials/{credentialId}/rotate": { "post": { "operationId": "rotateServiceCredential", "summary": "Rotate one active tenant service credential", "tags": [ "Service credentials" ], "security": [ { "tenantServiceCredential": [], "operatorCapability": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceCredentialSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "scopes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "delegableScopes": { "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } } }, "required": [ "serviceCredentialSchemaVersion", "commandId", "scopes", "delegableScopes" ], "additionalProperties": false } } }, "required": true }, "responses": { "201": { "description": "Replacement issued once; predecessor remains valid for at most 24 hours.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "serviceCredentialSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "credentialId": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "credential": { "type": "string", "maxLength": 96, "pattern": "^ldg_svc_v1\\.[a-z0-9-]{1,16}\\.[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}$" }, "scopes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "delegableScopes": { "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "operation": { "type": "string", "const": "create" }, "predecessorCredentialId": { "type": "null" }, "predecessorNotAfter": { "type": "null" } }, "required": [ "serviceCredentialSchemaVersion", "commandId", "credentialId", "credential", "scopes", "delegableScopes", "createdAt", "operation", "predecessorCredentialId", "predecessorNotAfter" ], "additionalProperties": false }, { "type": "object", "properties": { "serviceCredentialSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "credentialId": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "credential": { "type": "string", "maxLength": 96, "pattern": "^ldg_svc_v1\\.[a-z0-9-]{1,16}\\.[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}$" }, "scopes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "delegableScopes": { "maxItems": 32, "type": "array", "items": { "type": "string", "enum": [ "administrative:read", "lot:snapshot:read", "lot:provision", "issuer:manage", "webhook:endpoint:manage", "delivery:re-drive", "delivery:re-sync", "evidence:read", "intervention-audit:read", "intervention-audit:delete", "lot:amend-increments", "lot:pause", "lot:resume", "lot:extend", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore", "projection:revise", "capability:revoke", "issuer:revoke", "delivery:clear", "credential:manage" ] } }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "operation": { "type": "string", "const": "rotate" }, "predecessorCredentialId": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "predecessorNotAfter": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "serviceCredentialSchemaVersion", "commandId", "credentialId", "credential", "scopes", "delegableScopes", "createdAt", "operation", "predecessorCredentialId", "predecessorNotAfter" ], "additionalProperties": false } ] } } } }, "400": { "description": "Invalid request or credential id." }, "401": { "description": "Invalid or inactive service credential." }, "403": { "description": "Missing dual authority or requested scope exceeds the caller ceiling." }, "404": { "description": "Target not found in the authenticated tenant." }, "409": { "description": "Command conflict, inactive predecessor or final-manager protection." }, "503": { "description": "Credential lifecycle storage or verifier key is unavailable." } }, "parameters": [ { "in": "path", "name": "credentialId", "schema": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "required": true } ] } }, "/v1/service-credentials/{credentialId}": { "delete": { "operationId": "revokeServiceCredential", "summary": "Idempotently revoke one tenant service credential", "tags": [ "Service credentials" ], "security": [ { "tenantServiceCredential": [], "operatorCapability": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceCredentialSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "serviceCredentialSchemaVersion", "commandId" ], "additionalProperties": false } } }, "required": true }, "responses": { "204": { "description": "Target credential is revoked." }, "400": { "description": "Invalid request or credential id." }, "401": { "description": "Invalid or inactive service credential." }, "403": { "description": "Missing dual authority." }, "404": { "description": "Target not found in the authenticated tenant." }, "409": { "description": "Command conflict or final-manager protection." }, "503": { "description": "Credential lifecycle storage is unavailable." } }, "parameters": [ { "in": "path", "name": "credentialId", "schema": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$" }, "required": true } ] } }, "/v1/webhook-endpoints/{endpointId}": { "put": { "operationId": "putWebhookEndpoint", "summary": "Create a pending webhook endpoint revision", "description": "Creation uses If-None-Match: *. Rotation uses the current active revision ETag. No outbound challenge runs until the secret has been installed.", "tags": [ "Webhook endpoints" ], "security": [ { "tenantServiceCredential": [] } ], "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "*" ] }, "description": "Required for the first revision." }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\"webhook-endpoint-revision-[1-9][0-9]*\"$" }, "description": "Required for rotation or replacement after disable." }, { "in": "path", "name": "endpointId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "url": { "type": "string", "maxLength": 2048, "pattern": "^https:\\/\\/" } }, "required": [ "webhookEndpointSchemaVersion", "commandId", "url" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Idempotent command replay.", "headers": { "ETag": { "description": "Authoritative current or pending revision precondition.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Always no-store.", "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "pending" }, "url": { "type": "string", "maxLength": 2048, "pattern": "^https:\\/\\/" }, "key": { "type": "object", "properties": { "keyId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "secret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } }, "required": [ "keyId", "secret" ], "additionalProperties": false }, "challengeExpiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "idempotentReplay": { "type": "boolean" } }, "required": [ "webhookEndpointSchemaVersion", "commandId", "endpointId", "revision", "status", "url", "key", "challengeExpiresAt", "idempotentReplay" ], "additionalProperties": false }, { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "active", "disabled", "expired", "exhausted" ] }, "verifiedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "idempotentReplay": { "type": "boolean", "const": true } }, "required": [ "webhookEndpointSchemaVersion", "commandId", "endpointId", "revision", "status", "verifiedAt", "idempotentReplay" ], "additionalProperties": false } ] } } } }, "201": { "description": "Pending revision and installable secret. Never cache this response.", "headers": { "ETag": { "description": "Authoritative pending revision precondition.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Always no-store.", "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "pending" }, "url": { "type": "string", "maxLength": 2048, "pattern": "^https:\\/\\/" }, "key": { "type": "object", "properties": { "keyId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "secret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } }, "required": [ "keyId", "secret" ], "additionalProperties": false }, "challengeExpiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "idempotentReplay": { "type": "boolean" } }, "required": [ "webhookEndpointSchemaVersion", "commandId", "endpointId", "revision", "status", "url", "key", "challengeExpiresAt", "idempotentReplay" ], "additionalProperties": false }, { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "active", "disabled", "expired", "exhausted" ] }, "verifiedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "idempotentReplay": { "type": "boolean", "const": true } }, "required": [ "webhookEndpointSchemaVersion", "commandId", "endpointId", "revision", "status", "verifiedAt", "idempotentReplay" ], "additionalProperties": false } ] } } } }, "400": { "description": "Invalid request or syntactically unsafe URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "401": { "description": "Invalid or inactive service credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "403": { "description": "Missing endpoint-management scope or secret replay by a different credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "409": { "description": "Command conflict, pending revision, or current key grace prevents rotation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "412": { "description": "Creation or revision precondition does not match.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "428": { "description": "A creation or revision precondition is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "429": { "description": "Service-authentication admission is rate limited; Retry-After is present.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "500": { "description": "Unexpected internal failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "503": { "description": "Authentication, encryption, or durable state is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } } } } }, "/v1/webhook-endpoints/{endpointId}/verify": { "post": { "operationId": "verifyWebhookEndpoint", "summary": "Challenge and activate an installed pending webhook revision", "tags": [ "Webhook endpoints" ], "security": [ { "tenantServiceCredential": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"webhook-endpoint-pending-[1-9][0-9]*\"$" } }, { "in": "path", "name": "endpointId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "webhookEndpointSchemaVersion", "commandId", "revision" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "The revision is active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "active" }, "verifiedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "idempotentReplay": { "type": "boolean" } }, "required": [ "webhookEndpointSchemaVersion", "endpointId", "revision", "status", "verifiedAt", "idempotentReplay" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or the destination resolves to a forbidden address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "401": { "description": "Invalid or inactive service credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "403": { "description": "Missing endpoint-management scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "404": { "description": "Endpoint not found in the authenticated tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "409": { "description": "Challenge is running, expired, exhausted, or activation lost its CAS.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "412": { "description": "Pending revision precondition does not match.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "428": { "description": "If-Match is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "429": { "description": "Service-authentication admission is rate limited; Retry-After is present.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "500": { "description": "Unexpected internal failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "502": { "description": "The endpoint failed its bounded signed challenge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "503": { "description": "Authentication, D1, encryption, or pinned egress is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } } } } }, "/v1/webhook-endpoints/{endpointId}/disable": { "post": { "operationId": "disableWebhookEndpoint", "summary": "Idempotently disable a webhook endpoint and destroy its secrets", "tags": [ "Webhook endpoints" ], "security": [ { "tenantServiceCredential": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"webhook-endpoint-revision-[1-9][0-9]*\"$" } }, { "in": "path", "name": "endpointId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "webhookEndpointSchemaVersion", "commandId" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Endpoint is disabled and no longer resolvable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "status": { "type": "string", "const": "disabled" }, "disabledAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "idempotentReplay": { "type": "boolean" } }, "required": [ "webhookEndpointSchemaVersion", "commandId", "endpointId", "status", "disabledAt", "idempotentReplay" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "401": { "description": "Invalid or inactive service credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "403": { "description": "Missing endpoint-management scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "404": { "description": "Endpoint not found in the authenticated tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "409": { "description": "Command id conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "412": { "description": "Revision precondition does not match.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "428": { "description": "If-Match is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "429": { "description": "Service-authentication admission is rate limited; Retry-After is present.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "500": { "description": "Unexpected internal failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } }, "503": { "description": "Authentication or durable state is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookEndpointSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "revision_precondition_failed", "command_id_conflict", "pending_revision_exists", "rotation_grace_active", "challenge_in_progress", "challenge_expired", "challenge_exhausted", "unsafe_url", "challenge_failed", "secret_replay_forbidden", "rate_limited", "service_auth_unavailable", "webhook_endpoint_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "webhookEndpointSchemaVersion", "error" ], "additionalProperties": false } } } } } } }, "/v1/lots/{externalLotId}": { "put": { "operationId": "provisionLot", "summary": "Create or replace one scheduled lot", "description": "Identical desired state is idempotent. Changed state requires If-Match and is mutable only while scheduled.", "tags": [ "Provisioning" ], "security": [ { "tenantServiceCredential": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": false, "description": "Required for changed desired state: \"provision-revision-N\".", "schema": { "type": "string", "pattern": "^\"provision-revision-[1-9][0-9]*\"$" } }, { "in": "path", "name": "externalLotId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "responses": { "200": { "description": "Durably accepted by the LotActor; includes the current ETag.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Current provision revision." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "auctionId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "provisionRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "snapshotDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "scheduled", "open", "paused", "quarantined", "sealed" ] }, "idempotentReplay": { "type": "boolean" }, "rulebook": { "type": "object", "properties": { "rulebookSchemaVersion": { "type": "string", "const": "1.1" }, "canonicalizationVersion": { "type": "string", "const": "jcs-rfc8785-v1" }, "auctionMechanism": { "type": "string", "const": "english-proxy-v1" }, "context": { "type": "object", "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "auctionId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "tenantId", "auctionId", "lotId" ], "additionalProperties": false }, "schedule": { "type": "object", "properties": { "opensAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "originalClosesAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hardClosesAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "opensAt", "originalClosesAt", "hardClosesAt" ], "additionalProperties": false }, "economics": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "currencyDecimals": { "type": "integer", "minimum": 0, "maximum": 4 }, "startingPrice": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "reservePrice": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "reserveVisibility": { "type": "string", "enum": [ "hidden", "met", "amount" ] }, "increments": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "upTo", "amount" ], "additionalProperties": false } }, "incrementAlignment": { "type": "string", "enum": [ "strict", "free" ] }, "confirmationThresholdMultiple": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "currency", "currencyDecimals", "startingPrice", "reservePrice", "reserveVisibility", "increments", "incrementAlignment", "confirmationThresholdMultiple" ], "additionalProperties": false }, "antiSniping": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "disabled" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "extend-on-lead-change" }, "triggerWindowMs": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "extensionMs": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "mode", "triggerWindowMs", "extensionMs" ], "additionalProperties": false } ] }, "eligibility": { "type": "object", "properties": { "sellerSubjectId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "affiliateSubjectIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } }, "required": [ "sellerSubjectId", "affiliateSubjectIds" ], "additionalProperties": false } }, "required": [ "rulebookSchemaVersion", "canonicalizationVersion", "auctionMechanism", "context", "schedule", "economics", "antiSniping", "eligibility" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "lotId", "auctionId", "provisionRevision", "snapshotDigest", "state", "idempotentReplay", "rulebook" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } }, "403": { "description": "Credential lacks provisioning authority.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } }, "409": { "description": "Lot is no longer mutable or a tenant provisioning ceiling is occupied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } }, "412": { "description": "If-Match names a stale revision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } }, "428": { "description": "Changed desired state omitted If-Match.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } }, "502": { "description": "Actor did not durably accept the pending intent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } }, "503": { "description": "Service authentication is temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioningSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "precondition_required", "revision_mismatch", "ceiling_exceeded", "lot_not_mutable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "provisioningSchemaVersion", "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auctionExternalId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "projectionPolicy": { "type": "object", "properties": { "leaderIdentity": { "type": "boolean" }, "activity": { "type": "boolean" }, "recentHistory": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 50 }, { "type": "null" } ] } }, "required": [ "leaderIdentity", "activity", "recentHistory" ], "additionalProperties": false }, "rulebook": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "opensAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "originalClosesAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hardClosesAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "opensAt", "originalClosesAt", "hardClosesAt" ], "additionalProperties": false }, "economics": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "currencyDecimals": { "type": "integer", "minimum": 0, "maximum": 4 }, "startingPrice": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "reservePrice": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "reserveVisibility": { "type": "string", "enum": [ "hidden", "met", "amount" ] }, "increments": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "upTo", "amount" ], "additionalProperties": false } }, "incrementAlignment": { "type": "string", "enum": [ "strict", "free" ] }, "confirmationThresholdMultiple": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "currency", "currencyDecimals", "startingPrice", "reservePrice", "reserveVisibility", "increments", "incrementAlignment", "confirmationThresholdMultiple" ], "additionalProperties": false }, "antiSniping": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "disabled" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "extend-on-lead-change" }, "triggerWindowMs": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "extensionMs": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "mode", "triggerWindowMs", "extensionMs" ], "additionalProperties": false } ] }, "eligibility": { "type": "object", "properties": { "sellerSubjectId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "affiliateSubjectIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } }, "required": [ "sellerSubjectId", "affiliateSubjectIds" ], "additionalProperties": false } }, "required": [ "schedule", "economics", "antiSniping", "eligibility" ], "additionalProperties": false } }, "required": [ "auctionExternalId", "rulebook" ], "additionalProperties": false } } } } } }, "/v1/lots/{lotId}/interventions": { "post": { "operationId": "interveneLot", "summary": "Apply one authorized lot intervention", "description": "Tenant service authority and one exact lot-scoped operator capability are both required. Optional reasonDetail is Control-Plane-only and defaults to zero retention.", "tags": [ "Interventions" ], "security": [ { "tenantServiceCredential": [], "operatorCapability": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": false, "description": "Required only by lot:amend-increments: \"rulebook-revision-N\".", "schema": { "type": "string", "pattern": "^\"rulebook-revision-[1-9][0-9]*\"$" } }, { "in": "path", "name": "lotId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "lot:pause" }, "expectedState": { "type": "string", "const": "open" }, "pauseDurationMs": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "reasonCode": { "type": "string", "const": "operational_disruption" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "expectedState", "pauseDurationMs", "reasonCode" ], "additionalProperties": false }, { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "lot:resume" }, "expectedState": { "type": "string", "const": "paused" }, "reasonCode": { "type": "string", "const": "operational_disruption" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "expectedState", "reasonCode" ], "additionalProperties": false }, { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "lot:extend" }, "expectedState": { "type": "string", "enum": [ "open", "paused" ] }, "newClosesAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reasonCode": { "type": "string", "const": "operational_disruption" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "expectedState", "newClosesAt", "reasonCode" ], "additionalProperties": false }, { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "lot:amend-increments" }, "expectedState": { "type": "string", "enum": [ "open", "paused" ] }, "increments": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "upTo", "amount" ], "additionalProperties": false } }, "reasonCode": { "type": "string", "const": "increment_policy_correction" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "expectedState", "increments", "reasonCode" ], "additionalProperties": false }, { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "lot:cancel" }, "expectedState": { "type": "string", "enum": [ "scheduled", "open", "paused", "quarantined" ] }, "reasonCode": { "type": "string", "const": "auction_cancellation" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "expectedState", "reasonCode" ], "additionalProperties": false }, { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "lot:quarantine" }, "expectedState": { "type": "string", "enum": [ "open", "paused" ] }, "reasonCode": { "type": "string", "const": "suspected_storage_restore" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "expectedState", "reasonCode" ], "additionalProperties": false }, { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "lot:seal-quarantined" }, "expectedState": { "type": "string", "const": "quarantined" }, "reasonCode": { "type": "string", "const": "quarantine_finalization" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "expectedState", "reasonCode" ], "additionalProperties": false }, { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "lot:restore" }, "expectedState": { "type": "string", "enum": [ "open", "paused" ] }, "restoredToBookmark": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonCode": { "type": "string", "const": "storage_corruption" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "expectedState", "restoredToBookmark", "reasonCode" ], "additionalProperties": false } ] } } }, "required": true }, "responses": { "200": { "description": "The actor durably applied, replayed or armed the command.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "type": { "type": "string", "enum": [ "lot:pause", "lot:resume", "lot:extend", "lot:amend-increments", "lot:cancel", "lot:quarantine", "lot:seal-quarantined", "lot:restore" ] }, "status": { "type": "string", "enum": [ "pending", "complete" ] }, "recordSequence": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "scheduled", "open", "paused", "quarantined", "sealed" ] }, "interventionRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "replayed": { "type": "boolean" }, "audit": { "type": "object", "properties": { "stored": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "none", "committed", "reconciling" ] } }, "required": [ "stored", "expiresAt", "status" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "commandId", "type", "status", "recordSequence", "state", "interventionRevision", "replayed", "audit" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or an irrelevant If-Match header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "state_precondition_failed", "revision_precondition_failed", "command_id_conflict", "operation_in_progress", "lot_not_mutable", "hard_close_exceeded", "invalid_close_time", "invalid_increment_policy", "rule_not_implemented", "intervention_audit_unavailable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "error" ], "additionalProperties": false } } } }, "401": { "description": "Invalid or inactive tenant service credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "state_precondition_failed", "revision_precondition_failed", "command_id_conflict", "operation_in_progress", "lot_not_mutable", "hard_close_exceeded", "invalid_close_time", "invalid_increment_policy", "rule_not_implemented", "intervention_audit_unavailable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "error" ], "additionalProperties": false } } } }, "403": { "description": "Missing exact service scope or invalid lot-scoped operator capability.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "state_precondition_failed", "revision_precondition_failed", "command_id_conflict", "operation_in_progress", "lot_not_mutable", "hard_close_exceeded", "invalid_close_time", "invalid_increment_policy", "rule_not_implemented", "intervention_audit_unavailable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "error" ], "additionalProperties": false } } } }, "404": { "description": "Lot not found in the authenticated tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "state_precondition_failed", "revision_precondition_failed", "command_id_conflict", "operation_in_progress", "lot_not_mutable", "hard_close_exceeded", "invalid_close_time", "invalid_increment_policy", "rule_not_implemented", "intervention_audit_unavailable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "error" ], "additionalProperties": false } } } }, "409": { "description": "State, command identity or lot mutability conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "state_precondition_failed", "revision_precondition_failed", "command_id_conflict", "operation_in_progress", "lot_not_mutable", "hard_close_exceeded", "invalid_close_time", "invalid_increment_policy", "rule_not_implemented", "intervention_audit_unavailable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "error" ], "additionalProperties": false } } } }, "412": { "description": "Rulebook revision precondition failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "state_precondition_failed", "revision_precondition_failed", "command_id_conflict", "operation_in_progress", "lot_not_mutable", "hard_close_exceeded", "invalid_close_time", "invalid_increment_policy", "rule_not_implemented", "intervention_audit_unavailable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "error" ], "additionalProperties": false } } } }, "428": { "description": "lot:amend-increments omitted If-Match.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "state_precondition_failed", "revision_precondition_failed", "command_id_conflict", "operation_in_progress", "lot_not_mutable", "hard_close_exceeded", "invalid_close_time", "invalid_increment_policy", "rule_not_implemented", "intervention_audit_unavailable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "error" ], "additionalProperties": false } } } }, "503": { "description": "Actor or intervention audit is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "precondition_required", "state_precondition_failed", "revision_precondition_failed", "command_id_conflict", "operation_in_progress", "lot_not_mutable", "hard_close_exceeded", "invalid_close_time", "invalid_increment_policy", "rule_not_implemented", "intervention_audit_unavailable", "service_auth_unavailable", "actor_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 256 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "code", "message", "correlationId" ], "additionalProperties": false } }, "required": [ "interventionSchemaVersion", "error" ], "additionalProperties": false } } } } } } }, "/v1/intervention-audit/{commandId}/reason-detail": { "get": { "operationId": "readInterventionReasonDetail", "summary": "Read one retained tenant intervention detail", "tags": [ "Interventions" ], "security": [ { "tenantServiceCredential": [] } ], "responses": { "200": { "description": "Committed and unexpired encrypted detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionAuditSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "committedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "interventionAuditSchemaVersion", "commandId", "reasonDetail", "createdAt", "committedAt", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid command identifier." }, "401": { "description": "Invalid or inactive tenant service credential." }, "403": { "description": "Credential lacks intervention-audit:read." }, "404": { "description": "Detail is absent, pending, expired, deleted or belongs to another tenant." }, "503": { "description": "Audit storage or cryptographic keyring is unavailable." } }, "parameters": [ { "in": "path", "name": "commandId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ] }, "delete": { "operationId": "deleteInterventionReasonDetail", "summary": "Idempotently delete one retained tenant intervention detail", "tags": [ "Interventions" ], "security": [ { "tenantServiceCredential": [] } ], "responses": { "204": { "description": "Detail is absent after this request." }, "400": { "description": "Invalid command identifier." }, "401": { "description": "Invalid or inactive tenant service credential." }, "403": { "description": "Credential lacks intervention-audit:delete." }, "503": { "description": "Audit deletion could not be made durable." } }, "parameters": [ { "in": "path", "name": "commandId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ] } }, "/v1/delivery/re-drive": { "post": { "operationId": "reDriveDelivery", "summary": "Request one immutable delivery replay", "tags": [ "Recovery" ], "security": [ { "tenantServiceCredential": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 128 }, "reason": { "type": "string", "minLength": 1, "maxLength": 512 }, "endpointRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "eventId", "reason", "endpointRevision" ], "additionalProperties": false } } }, "required": true }, "responses": { "202": { "description": "An exhausted delivery was durably audited and queued." }, "400": { "description": "Invalid endpoint revision or request." }, "401": { "description": "Invalid credential." }, "403": { "description": "Missing delivery:re-drive scope." }, "409": { "description": "Delivery is not exhausted, is already resolved, or still has a live lease." }, "429": { "description": "Recovery rate limit exceeded." }, "503": { "description": "Verified archive or replay queue unavailable." } } } }, "/v1/delivery/re-sync": { "post": { "operationId": "reSyncDelivery", "summary": "Queue a bounded, tenant-scoped recovery page", "tags": [ "Recovery" ], "security": [ { "tenantServiceCredential": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auctionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "lotId": { "type": "string", "minLength": 1, "maxLength": 128 }, "fromSequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "toSequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "fromOccurredAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "toOccurredAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cursor": { "type": "string", "maxLength": 512 }, "reason": { "type": "string", "minLength": 1, "maxLength": 512 }, "endpointRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "endpointRevision" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Fixed recovery page queued." }, "400": { "description": "Invalid range, endpoint revision, or cursor." }, "401": { "description": "Invalid credential." }, "403": { "description": "Missing delivery:re-sync scope." }, "429": { "description": "Recovery rate limit exceeded." }, "503": { "description": "A per-event failure was audited; response carries an exact resume cursor." } } } }, "/v1/deliveries/{eventId}/clear": { "post": { "operationId": "clearDelivery", "summary": "Dispose one 24h soft delivery attention with dual authority", "tags": [ "Recovery" ], "security": [ { "tenantServiceCredential": [], "operatorCapability": [] } ], "parameters": [ { "in": "path", "name": "eventId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryClearSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonCode": { "type": "string", "enum": [ "tenant_confirmed_receipt", "tenant_waived_delivery", "duplicate_confirmed_out_of_band" ] } }, "required": [ "deliveryClearSchemaVersion", "commandId", "reasonCode" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Delivery is cleared, or the same semantic command was replayed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryClearSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "disposition": { "type": "string", "const": "cleared" }, "clearedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "clearedBySubjectId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonCode": { "type": "string", "enum": [ "tenant_confirmed_receipt", "tenant_waived_delivery", "duplicate_confirmed_out_of_band" ] }, "replayed": { "type": "boolean" } }, "required": [ "deliveryClearSchemaVersion", "commandId", "eventId", "disposition", "clearedAt", "clearedBySubjectId", "reasonCode", "replayed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing delivery:clear scope or invalid lot-scoped operator capability." }, "404": { "description": "Event not found in the authenticated tenant." }, "409": { "description": "Command conflict, non-pending delivery, missing or hard attention, or live lease." }, "503": { "description": "Clearance could not be made durable." } } } }, "/v1/evidence/{eventId}": { "get": { "operationId": "readEvidence", "summary": "Read one authorized, verified immutable delivery envelope", "tags": [ "Recovery" ], "security": [ { "tenantServiceCredential": [] } ], "parameters": [ { "in": "path", "name": "eventId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "responses": { "200": { "description": "Canonical byte-exact DeliveryEvent JSON." }, "401": { "description": "Invalid credential." }, "403": { "description": "Missing evidence:read scope." }, "404": { "description": "Event is not in this tenant archive." }, "429": { "description": "Evidence read rate limit exceeded." }, "503": { "description": "Verified archive reader unavailable." } } } }, "/v1/lots/{lotId}/record": { "get": { "operationId": "pullRecord", "summary": "Stream one complete tenant-custody evidence set", "description": "D-116 JSON Text Sequence: one record-pull-v1 header, then one bounded evidence chunk per manifest ordinal.", "tags": [ "Evidence" ], "security": [ { "tenantServiceCredential": [] } ], "parameters": [ { "in": "path", "name": "lotId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "responses": { "200": { "description": "Authenticated full-custody record stream.", "content": { "application/json-seq": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, invalid or revoked credential, or suspended tenant." }, "403": { "description": "Credential lacks the evidence:read custody scope." }, "404": { "description": "Record is absent, belongs to another tenant, or its auction is not fully terminal." }, "429": { "description": "Evidence read rate limit exceeded." }, "503": { "description": "Indexed evidence is unavailable or inconsistent." } } } }, "/v1/issuers/{issuerId}": { "put": { "operationId": "upsertIssuer", "summary": "Register or rotate one tenant JWKS source", "tags": [ "Issuers" ], "security": [ { "tenantServiceCredential": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "issuerSchemaVersion": { "type": "string", "const": "1.0" }, "issuer": { "type": "string", "maxLength": 512, "format": "uri" }, "jwksUri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sourceVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "freshnessMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 86400000 }, "l1TtlMs": { "type": "integer", "minimum": 0, "maximum": 60000 }, "ttlCeilingSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "issuerSchemaVersion", "issuer", "jwksUri", "sourceVersion", "freshnessMs", "l1TtlMs", "ttlCeilingSeconds" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Issuer source and its validated cache projection are active." }, "400": { "description": "Invalid issuer source." }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing issuer:manage scope." }, "409": { "description": "Issuer identity conflicts or was disabled." }, "503": { "description": "Issuer source could not converge." } }, "parameters": [ { "in": "path", "name": "issuerId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ] }, "delete": { "operationId": "disableIssuer", "summary": "Permanently disable one tenant issuer source", "tags": [ "Issuers" ], "security": [ { "tenantServiceCredential": [] } ], "responses": { "204": { "description": "Issuer disabled; repeats are idempotent." }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing issuer:manage scope." }, "404": { "description": "Issuer not found in the authenticated tenant." }, "503": { "description": "Disable is durable but cache removal remains pending." } }, "parameters": [ { "in": "path", "name": "issuerId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ] } }, "/v1/issuers/{issuerId}/keys/refresh": { "post": { "operationId": "refreshIssuer", "summary": "Refresh one active tenant JWKS projection", "tags": [ "Issuers" ], "security": [ { "tenantServiceCredential": [] } ], "responses": { "204": { "description": "Validated projection refreshed." }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing issuer:manage scope." }, "404": { "description": "Issuer not found in the authenticated tenant." }, "409": { "description": "Issuer is disabled." }, "503": { "description": "Refresh failed; bounded last-known projection remains until expiry." } }, "parameters": [ { "in": "path", "name": "issuerId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ] } }, "/v1/auctions/{auctionId}/capabilities/revoke": { "post": { "operationId": "revokeAuctionCapability", "summary": "Revoke one JTI or subject across an auction", "tags": [ "Revocation" ], "security": [ { "tenantServiceCredential": [], "operatorCapability": [] } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "revocationSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonCode": { "type": "string", "const": "capability_compromise" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 2048 }, "scope": { "type": "string", "const": "jti" }, "jti": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "denyUntil": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "revocationSchemaVersion", "commandId", "reasonCode", "scope", "jti", "denyUntil" ], "additionalProperties": false }, { "type": "object", "properties": { "revocationSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonCode": { "type": "string", "const": "capability_compromise" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 2048 }, "scope": { "type": "string", "const": "subject" }, "subjectId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "revocationSchemaVersion", "commandId", "reasonCode", "scope", "subjectId" ], "additionalProperties": false } ] } } }, "required": true }, "responses": { "202": { "description": "Revocation and target set are durable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revocationSchemaVersion": { "type": "string", "const": "1.0" }, "revocationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "status": { "type": "string", "enum": [ "pending", "complete" ] }, "statusUrl": { "type": "string", "minLength": 1, "maxLength": 2048 }, "replayed": { "type": "boolean" }, "audit": { "type": "object", "properties": { "stored": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "none", "committed", "reconciling" ] } }, "required": [ "stored", "expiresAt", "status" ], "additionalProperties": false } }, "required": [ "revocationSchemaVersion", "revocationId", "commandId", "status", "statusUrl", "replayed", "audit" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request or denyUntil." }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing scope or invalid operator capability." }, "404": { "description": "Auction not found in authenticated tenant." }, "409": { "description": "Command id conflict." }, "503": { "description": "Revocation could not be made durable." } }, "parameters": [ { "in": "path", "name": "auctionId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ] } }, "/v1/auctions/{auctionId}/interventions": { "post": { "operationId": "reviseAuctionProjection", "summary": "Revise the presentation policy across every live lot in an auction", "tags": [ "Interventions" ], "security": [ { "tenantServiceCredential": [], "operatorCapability": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "Current auction projection revision: \"projection-revision-N\".", "schema": { "type": "string", "pattern": "^\"projection-revision-[1-9][0-9]*\"$" } }, { "in": "path", "name": "auctionId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "interventionSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "type": { "type": "string", "const": "projection:revise" }, "policy": { "type": "object", "properties": { "leaderIdentity": { "type": "boolean" }, "activity": { "type": "boolean" }, "recentHistory": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 50 }, { "type": "null" } ] } }, "required": [ "leaderIdentity", "activity", "recentHistory" ], "additionalProperties": false }, "reasonCode": { "type": "string", "const": "projection_policy_correction" } }, "required": [ "interventionSchemaVersion", "commandId", "type", "policy", "reasonCode" ], "additionalProperties": false } } }, "required": true }, "responses": { "202": { "description": "The durable fan-out operation was accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projectionRevisionSchemaVersion": { "type": "string", "const": "1.0" }, "operationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "status": { "type": "string", "enum": [ "pending", "complete" ] }, "projectionRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "statusUrl": { "type": "string", "minLength": 1, "maxLength": 2048 }, "replayed": { "type": "boolean" }, "audit": { "type": "object", "properties": { "stored": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "none", "committed", "reconciling" ] } }, "required": [ "stored", "expiresAt", "status" ], "additionalProperties": false } }, "required": [ "projectionRevisionSchemaVersion", "operationId", "commandId", "status", "projectionRevision", "statusUrl", "replayed", "audit" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing scope or invalid operator capability." }, "404": { "description": "Auction not found in the authenticated tenant." }, "409": { "description": "Command conflict or an earlier revision is still reconciling." }, "412": { "description": "Projection revision precondition is stale or malformed." }, "428": { "description": "If-Match is required." }, "503": { "description": "Revision could not be made durable." } } } }, "/v1/projection-revisions/{operationId}": { "get": { "operationId": "getProjectionRevision", "summary": "Read bounded per-lot progress for one projection revision", "tags": [ "Interventions" ], "security": [ { "tenantServiceCredential": [] } ], "responses": { "200": { "description": "Current projection fan-out progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projectionRevisionSchemaVersion": { "type": "string", "const": "1.0" }, "operationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "status": { "type": "string", "enum": [ "pending", "complete" ] }, "projectionRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "policy": { "type": "object", "properties": { "leaderIdentity": { "type": "boolean" }, "activity": { "type": "boolean" }, "recentHistory": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 50 }, { "type": "null" } ] } }, "required": [ "leaderIdentity", "activity", "recentHistory" ], "additionalProperties": false }, "counts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "terminal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unavailable": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "pending", "applied", "terminal", "unavailable" ], "additionalProperties": false }, "targets": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "status": { "type": "string", "enum": [ "pending", "applied", "terminal", "unavailable" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recordSequence": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastErrorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "lotId", "status", "attempts", "recordSequence", "lastErrorCode" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] } }, "required": [ "projectionRevisionSchemaVersion", "operationId", "commandId", "status", "projectionRevision", "policy", "counts", "targets", "nextCursor" ], "additionalProperties": false } } } }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing projection:revise scope." }, "404": { "description": "Operation not found in authenticated tenant." }, "503": { "description": "Status unavailable." } }, "parameters": [ { "in": "path", "name": "operationId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true }, { "in": "query", "name": "cursor", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } ] } }, "/v1/tenants/{tenantId}/issuers/{issuerId}/revoke": { "post": { "operationId": "revokeIssuer", "summary": "Revoke one tenant issuer identity", "tags": [ "Revocation" ], "security": [ { "tenantServiceCredential": [], "operatorCapability": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "revocationSchemaVersion": { "type": "string", "const": "1.0" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "reasonCode": { "type": "string", "const": "capability_compromise" }, "reasonDetail": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "revocationSchemaVersion", "commandId", "reasonCode" ], "additionalProperties": false } } }, "required": true }, "responses": { "202": { "description": "Issuer revocation and target set are durable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revocationSchemaVersion": { "type": "string", "const": "1.0" }, "revocationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "status": { "type": "string", "enum": [ "pending", "complete" ] }, "statusUrl": { "type": "string", "minLength": 1, "maxLength": 2048 }, "replayed": { "type": "boolean" }, "audit": { "type": "object", "properties": { "stored": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "none", "committed", "reconciling" ] } }, "required": [ "stored", "expiresAt", "status" ], "additionalProperties": false } }, "required": [ "revocationSchemaVersion", "revocationId", "commandId", "status", "statusUrl", "replayed", "audit" ], "additionalProperties": false } } } }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing scope or invalid operator capability." }, "404": { "description": "Tenant or issuer not found." }, "409": { "description": "Command id conflict." }, "503": { "description": "Revocation could not be made durable." } }, "parameters": [ { "in": "path", "name": "tenantId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true }, { "in": "path", "name": "issuerId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true } ] } }, "/v1/revocations/{revocationId}": { "get": { "operationId": "getRevocation", "summary": "Read bounded per-lot revocation progress", "tags": [ "Revocation" ], "security": [ { "tenantServiceCredential": [] } ], "responses": { "200": { "description": "Current revocation progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revocationSchemaVersion": { "type": "string", "const": "1.0" }, "revocationId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "commandId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "scope": { "type": "string", "enum": [ "jti", "subject", "issuer" ] }, "status": { "type": "string", "enum": [ "pending", "complete" ] }, "counts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "terminal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unavailable": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "pending", "applied", "terminal", "unavailable" ], "additionalProperties": false }, "targets": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "lotId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "status": { "type": "string", "enum": [ "pending", "applied", "terminal", "unavailable" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastErrorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "lotId", "status", "attempts", "lastErrorCode" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] } }, "required": [ "revocationSchemaVersion", "revocationId", "commandId", "scope", "status", "counts", "targets", "nextCursor" ], "additionalProperties": false } } } }, "401": { "description": "Invalid service credential." }, "403": { "description": "Missing revocation scope." }, "404": { "description": "Revocation not found in authenticated tenant." }, "503": { "description": "Status unavailable." } }, "parameters": [ { "in": "path", "name": "revocationId", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "required": true }, { "in": "query", "name": "cursor", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } ] } } } }