{ "openapi": "3.0.0", "paths": { "/v1/keys": { "get": { "operationId": "KeysController_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated key list" } }, "security": [ { "bearer": [] } ], "summary": "List virtual keys (cursor-paginated)", "tags": [ "keys" ] }, "post": { "operationId": "KeysController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyDto" } } } }, "responses": { "201": { "description": "Key created — rawKey shown once" } }, "security": [ { "bearer": [] } ], "summary": "Create a virtual key with a budget", "tags": [ "keys" ] } }, "/v1/keys/{id}/limits": { "patch": { "operationId": "KeysController_updateLimits", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKeyLimitsDto" } } } }, "responses": { "200": { "description": "Updated rate limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyLimitsResponseDto" } } } }, "404": { "description": "Key not found" } }, "security": [ { "bearer": [] } ], "summary": "Set RPM / TPM rate limits on a key", "tags": [ "keys" ] } }, "/v1/keys/{id}/assign": { "patch": { "operationId": "KeysController_assign", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignKeyDto" } } } }, "responses": { "200": { "description": "Updated owner/team assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignKeyResponseDto" } } } }, "404": { "description": "Key, owner, or team not found" } }, "security": [ { "bearer": [] } ], "summary": "Reassign a key’s owner and/or cost-center team", "tags": [ "keys" ] } }, "/v1/keys/{id}": { "delete": { "operationId": "KeysController_revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Revoke a virtual key", "tags": [ "keys" ] } }, "/v1/user-limits": { "get": { "operationId": "UserLimitsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List all user limits for tenant", "tags": [ "user-limits" ] } }, "/v1/user-limits/{userId}": { "patch": { "operationId": "UserLimitsController_update", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserLimitDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a user limit", "tags": [ "user-limits" ] } }, "/v1/budgets": { "get": { "operationId": "BudgetsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List budgets for tenant", "tags": [ "budgets" ] } }, "/v1/budgets/{id}": { "patch": { "operationId": "BudgetsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBudgetDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update budget limit; syncs to Redis immediately", "tags": [ "budgets" ] } }, "/v1/budgets/requests": { "get": { "operationId": "BudgetsController_listRequests", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "pending", "approved", "denied", "revoked", "expired", "all" ], "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List budget requests", "tags": [ "budgets" ] }, "post": { "operationId": "BudgetsController_createRequest", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBudgetRequestDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Submit a budget increase request", "tags": [ "budgets" ] } }, "/v1/budgets/requests/{id}/approve": { "post": { "operationId": "BudgetsController_approve", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Approve a budget request (manager): applies the elevated limit for the requested window", "tags": [ "budgets" ] } }, "/v1/budgets/requests/{id}/deny": { "post": { "operationId": "BudgetsController_deny", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Deny a budget request (manager)", "tags": [ "budgets" ] } }, "/v1/budgets/requests/{id}/revoke": { "post": { "operationId": "BudgetsController_revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Revoke an active approved increase early (manager): restores the prior budget", "tags": [ "budgets" ] } }, "/v1/policies": { "get": { "operationId": "PoliciesController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List all policies for tenant", "tags": [ "policies" ] }, "post": { "operationId": "PoliciesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a policy", "tags": [ "policies" ] } }, "/v1/policies/{id}": { "patch": { "operationId": "PoliciesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePolicyDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a policy", "tags": [ "policies" ] }, "delete": { "operationId": "PoliciesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a policy", "tags": [ "policies" ] } }, "/v1/usage": { "get": { "operationId": "AnalyticsController_getUsageSummary", "parameters": [ { "name": "range", "required": false, "in": "query", "schema": { "example": "7d" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Spend summary for the given range", "tags": [ "analytics" ] } }, "/v1/usage/trend": { "get": { "operationId": "AnalyticsController_getUsageTrend", "parameters": [ { "name": "range", "required": false, "in": "query", "schema": { "example": "7d" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Daily spend trend", "tags": [ "analytics" ] } }, "/v1/anomalies": { "get": { "operationId": "AnalyticsController_getAnomalies", "parameters": [ { "name": "range", "required": false, "in": "query", "schema": { "example": "24h" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Recent guardrail events (blocks + redactions)", "tags": [ "analytics" ] } }, "/v1/cache": { "get": { "operationId": "AnalyticsController_getCacheStats", "parameters": [ { "name": "range", "required": false, "in": "query", "schema": { "example": "7d" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Cache hit rates and savings", "tags": [ "analytics" ] } }, "/v1/developer/sessions": { "get": { "description": "Scoped to the authenticated API key — a key can only read its own usage.", "operationId": "AnalyticsController_getDeveloperSessions", "parameters": [ { "name": "range", "required": false, "in": "query", "schema": { "example": "7d" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Sessions and KPIs for the calling API key", "tags": [ "analytics" ] } }, "/v1/search": { "get": { "operationId": "AnalyticsController_search", "parameters": [ { "name": "q", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Search across users, keys, and policies", "tags": [ "analytics" ] } }, "/v1/receipts": { "get": { "description": "Returns receipts for the authenticated tenant ordered by seq DESC, with optional AND-combined filters. Does NOT verify ED25519 signatures per row — call GET /v1/receipts/:id to verify a specific receipt. Use `cursor` (seq from the previous page) for cursor pagination; filters compose with the cursor. For control-scoped queries (e.g. all receipts proving eu_ai_act:art_12) use GET /v1/compliance/coverage/{framework}/controls/{controlId}/receipts. Receipts live in the hot analytics window (typically 7–30 days) until the WORM cold tier ships.", "operationId": "ReceiptsController_listReceipts", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Exclusive seq upper bound for the next page", "schema": { "type": "number" } }, { "name": "from", "required": false, "in": "query", "description": "RFC3339 lower ts bound (inclusive)", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "RFC3339 upper ts bound (inclusive)", "schema": { "type": "string" } }, { "name": "actor", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "provider", "required": false, "in": "query", "schema": { "example": "anthropic", "type": "string" } }, { "name": "model", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "check", "required": false, "in": "query", "description": "A check name present on the receipt (e.g. GUARDRAIL)", "schema": { "type": "string" } }, { "name": "upstreamStatus", "required": false, "in": "query", "schema": { "example": "ok", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentReceiptListDto" } } } }, "400": { "description": "Malformed from/to timestamp" } }, "security": [ { "bearer": [] } ], "summary": "Query receipts (newest first, filterable)", "tags": [ "receipts" ] } }, "/v1/receipts/export": { "get": { "description": "Returns the receipts matching the same filters as GET /v1/receipts, ordered by seq ASC, as a downloadable file. JSONL preserves each receipt’s signed canonical + chain fields (this_hash, signature, key_id) plus the unsigned `kind` side channel; CSV is a flat analyst-friendly projection (with a trailing `kind` column). Note: full offline chain verification needs the Evidence Bundle (GET /v1/compliance/evidence-bundle), which also carries the signing-key registry + trust anchor — a filtered export has seq gaps and omits the keys. Bounded per call by `limit` (max 50000); the `X-Wardin-Truncated` response header is true when more rows matched. Narrow with filters or page GET /v1/receipts.", "operationId": "ReceiptsController_exportReceipts", "parameters": [ { "name": "format", "required": false, "in": "query", "schema": { "enum": [ "jsonl", "csv" ], "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Row cap (max 50000)", "schema": { "example": 10000, "type": "number" } }, { "name": "from", "required": false, "in": "query", "description": "RFC3339 lower ts bound (inclusive)", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "RFC3339 upper ts bound (inclusive)", "schema": { "type": "string" } }, { "name": "actor", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "provider", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "model", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "check", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "upstreamStatus", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSONL or CSV file of the matched receipts (attachment)." }, "400": { "description": "Malformed from/to timestamp" } }, "security": [ { "bearer": [] } ], "summary": "Bulk export matched receipts (JSONL or CSV)", "tags": [ "receipts" ] } }, "/v1/receipts/{id}": { "get": { "description": "Returns the stored receipt row and a verified flag. verified=true means this_hash == sha256(canonical||prev_hash) AND the ED25519 signature over this_hash is valid. Tenant-scoped: you can only read receipts belonging to your tenant.", "operationId": "ReceiptsController_getReceipt", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "receipt_id (UUID)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptResponseDto" } } } }, "404": { "description": "Receipt not found" } }, "security": [ { "bearer": [] } ], "summary": "Get a single receipt by ID + verify its hash and signature", "tags": [ "receipts" ] } }, "/v1/receipts/{id}/verify-chain": { "get": { "description": "Walks receipts in seq order [from, to] for this tenant and re-derives each this_hash from stored fields. Reports the first broken or missing link.", "operationId": "ReceiptsController_verifyChain", "parameters": [ { "name": "from", "required": true, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "to", "required": true, "in": "query", "schema": { "example": "100", "type": "number" } }, { "name": "id", "required": true, "in": "path", "description": "Ignored — present for route grouping; use from/to", "schema": {} } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainVerifyResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Verify a contiguous seq range of the receipt chain", "tags": [ "receipts" ] } }, "/v1/webhooks/clerk": { "post": { "operationId": "WebhooksController_handleClerkWebhook", "parameters": [ { "name": "svix-id", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "svix-timestamp", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "svix-signature", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Receive Clerk webhook events to sync users and orgs", "tags": [ "webhooks" ] } }, "/v1/webhooks/github": { "post": { "operationId": "GithubWebhookController_handleGithubWebhook", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Receive GitHub pull_request webhook events for PR-outcome quality signals (QUAL-1)", "tags": [ "webhooks" ] } }, "/v1/quality-signals/github-link": { "post": { "operationId": "GithubLinkController_link", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubLinkDto" } } } }, "responses": { "201": { "description": "" }, "400": { "description": "Malformed pr identity" } }, "security": [ { "bearer": [] } ], "summary": "Explicitly link a Wardin session to a GitHub PR outcome — the universal escape hatch for CI pipelines or setups the webhook receiver cannot reach (§3(e))", "tags": [ "quality-signals" ] } }, "/v1/team/members": { "get": { "operationId": "TeamController_listMembers", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMemberDto" } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all team members for the tenant", "tags": [ "team" ] } }, "/v1/team/members/invite": { "post": { "operationId": "TeamController_invite", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberDto" } } } }, "responses": { "201": { "description": "Invitation sent" } }, "security": [ { "bearer": [] } ], "summary": "Invite a new team member by email", "tags": [ "team" ] } }, "/v1/team/members/{userId}/role": { "patch": { "operationId": "TeamController_updateRole", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleDto" } } } }, "responses": { "200": { "description": "Role updated" } }, "security": [ { "bearer": [] } ], "summary": "Update a team member's role", "tags": [ "team" ] } }, "/v1/team/members/{userId}": { "delete": { "operationId": "TeamController_removeMember", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Member removed" } }, "security": [ { "bearer": [] } ], "summary": "Remove a team member", "tags": [ "team" ] } }, "/v1/team/teams": { "get": { "operationId": "TeamController_listTeams", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamDto" } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all teams for the tenant", "tags": [ "team" ] }, "post": { "operationId": "TeamController_createTeam", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a new team", "tags": [ "team" ] } }, "/v1/team/teams/{teamId}": { "patch": { "operationId": "TeamController_renameTeam", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameTeamDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Rename a team or update its budget pool", "tags": [ "team" ] }, "delete": { "operationId": "TeamController_deleteTeam", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Team deleted" } }, "security": [ { "bearer": [] } ], "summary": "Delete a team (users are unassigned, not deleted)", "tags": [ "team" ] } }, "/v1/team/members/{userId}/team": { "patch": { "operationId": "TeamController_assignUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignUserDto" } } } }, "responses": { "200": { "description": "Team assignment updated" } }, "security": [ { "bearer": [] } ], "summary": "Assign or unassign a user to/from a team", "tags": [ "team" ] } }, "/v1/webhook-endpoints": { "get": { "operationId": "AlertingController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List outbound webhook endpoints for tenant", "tags": [ "webhook-endpoints" ] }, "post": { "operationId": "AlertingController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create an outbound webhook endpoint (generates a signing secret)", "tags": [ "webhook-endpoints" ] } }, "/v1/webhook-endpoints/{id}": { "patch": { "operationId": "AlertingController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update an outbound webhook endpoint", "tags": [ "webhook-endpoints" ] }, "delete": { "operationId": "AlertingController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete an outbound webhook endpoint", "tags": [ "webhook-endpoints" ] } }, "/v1/webhook-endpoints/{id}/test": { "post": { "operationId": "AlertingController_test", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Send a signed test event to the endpoint and return the result", "tags": [ "webhook-endpoints" ] } }, "/v1/billing/subscription": { "get": { "operationId": "BillingController_subscription", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Current plan + usage-vs-limit for the tenant", "tags": [ "billing" ] } }, "/v1/billing/checkout": { "post": { "operationId": "BillingController_checkout", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a Stripe Checkout session to upgrade plan", "tags": [ "billing" ] } }, "/v1/billing/portal": { "post": { "operationId": "BillingController_portal", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePortalDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a Stripe billing-portal session", "tags": [ "billing" ] } }, "/v1/prompts": { "get": { "operationId": "PromptsController_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PromptDto" } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all prompts for the tenant (with label map)", "tags": [ "prompts" ] }, "post": { "operationId": "PromptsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a new prompt (also creates version 1)", "tags": [ "prompts" ] } }, "/v1/prompts/{promptId}/versions": { "get": { "operationId": "PromptsController_getVersions", "parameters": [ { "name": "promptId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PromptVersionDto" } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all versions for a prompt", "tags": [ "prompts" ] } }, "/v1/prompts/versions": { "post": { "operationId": "PromptsController_createVersion", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptVersionDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Append a new version to an existing prompt", "tags": [ "prompts" ] } }, "/v1/prompts/labels": { "post": { "operationId": "PromptsController_setLabel", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetLabelDto" } } } }, "responses": { "204": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Point a named label at a specific version", "tags": [ "prompts" ] } }, "/v1/prompts/run": { "post": { "operationId": "PromptsController_run", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPromptDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunResultDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Run a prompt version through the gateway playground", "tags": [ "prompts" ] } }, "/v1/prompts/{id}/label/{label}": { "get": { "operationId": "PromptsController_resolveLabel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "label", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedLabelDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Resolve a label to the pinned version content", "tags": [ "prompts" ] } }, "/v1/providers": { "get": { "operationId": "ProvidersController_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderCredentialResponseDto" } } } } } }, "security": [ { "bearer": [] } ], "summary": "List stored provider credentials (masked)", "tags": [ "providers" ] } }, "/v1/providers/{provider}": { "put": { "operationId": "ProvidersController_upsert", "parameters": [ { "name": "provider", "required": true, "in": "path", "schema": { "enum": [ "anthropic", "openai", "bedrock", "vertex" ], "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertProviderCredentialDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCredentialResponseDto" } } } }, "400": { "description": "Invalid credentials shape" } }, "security": [ { "bearer": [] } ], "summary": "Create or replace credentials for a provider", "tags": [ "providers" ] }, "delete": { "operationId": "ProvidersController_remove", "parameters": [ { "name": "provider", "required": true, "in": "path", "schema": { "enum": [ "anthropic", "openai", "bedrock", "vertex" ], "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "No stored credentials for provider" } }, "security": [ { "bearer": [] } ], "summary": "Remove stored credentials for a provider", "tags": [ "providers" ] } }, "/v1/providers/{provider}/test": { "post": { "operationId": "ProvidersController_test", "parameters": [ { "name": "provider", "required": true, "in": "path", "schema": { "enum": [ "anthropic", "openai", "bedrock", "vertex" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderTestResultDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Test stored credentials with a minimal upstream call", "tags": [ "providers" ] } }, "/v1/compliance/frameworks": { "get": { "operationId": "ComplianceController_listFrameworks", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameworkListDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List available compliance frameworks (one in-force pack each)", "tags": [ "compliance" ] } }, "/v1/compliance/coverage/{framework}": { "get": { "description": "Splits a framework’s controls into enforced (proven per-request on the enforcement path), partial, and external (document elsewhere). Carries a legal-posture disclaimer to surface verbatim.", "operationId": "ComplianceController_getCoverageMap", "parameters": [ { "name": "framework", "required": true, "in": "path", "schema": { "example": "eu_ai_act", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageMapDto" } } } }, "404": { "description": "Unknown framework" } }, "security": [ { "bearer": [] } ], "summary": "Coverage map for a framework", "tags": [ "compliance" ] } }, "/v1/compliance/receipts/{id}/controls": { "get": { "description": "For one receipt (tenant-scoped), the framework control IDs each of its checks satisfies under the in-force pack. Optional ?framework filters to one.", "operationId": "ComplianceController_getReceiptControls", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "receipt_id (UUID)", "schema": { "type": "string" } }, { "name": "framework", "required": false, "in": "query", "schema": { "example": "eu_ai_act", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptControlsDto" } } } }, "400": { "description": "Malformed receipt id (not a UUID)" }, "404": { "description": "Receipt or framework not found" } }, "security": [ { "bearer": [] } ], "summary": "Controls a receipt’s checks satisfy", "tags": [ "compliance" ] } }, "/v1/compliance/coverage/{framework}/controls/{controlId}/receipts": { "get": { "description": "Scans the signed receipt chain for the checks that prove this control (pack `proven_by`), within `range`. `enforced` covers PASS/BLOCKED/REDACTED — all are evidence the control ran in-path; `failed` marks a technical/upstream failure on a proving check; `indeterminate` marks an unrecognized proving-check result (never assumed enforced). `summary` is an accurate aggregate over the whole window; `receipts` is a capped sample page — use `nextCursor` to page.", "operationId": "ComplianceController_queryByControl", "parameters": [ { "name": "framework", "required": true, "in": "path", "schema": { "example": "eu_ai_act", "type": "string" } }, { "name": "controlId", "required": true, "in": "path", "schema": { "example": "eu_ai_act:art_12", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 100, "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "seq from a previous page’s nextCursor, to page forward.", "schema": { "type": "string" } }, { "name": "range", "required": false, "in": "query", "description": "Compact window, `Nd` or `Nh` (e.g. 7d, 24h).", "schema": { "example": "7d" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlReceiptsDto" } } } }, "400": { "description": "Malformed `range` (must match `Nd` or `Nh`)" }, "404": { "description": "Unknown framework or control" } }, "security": [ { "bearer": [] } ], "summary": "Receipts where a control was applied, this period", "tags": [ "compliance" ] } }, "/v1/compliance/evidence-bundle": { "get": { "description": "Assembles a contiguous signed receipt segment for `range`, the signing-key registry covering those receipts (rotation-safe), the compliance packs in force, and a trust anchor. Verify it offline with the open-source wardin-verify CLI — no Wardin account or network needed. Produces audit-grade / Art-12-grade records for gateway-routed traffic; NOT a compliance certification.", "operationId": "ComplianceController_exportBundle", "parameters": [ { "name": "range", "required": false, "in": "query", "description": "Compact window, `Nd` or `Nh` (e.g. 30d, 24h).", "schema": { "example": "30d" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceBundleDto" } } } }, "400": { "description": "Malformed `range` (must match `Nd` or `Nh`)" } }, "security": [ { "bearer": [] } ], "summary": "Export a self-contained, offline-verifiable Evidence Bundle", "tags": [ "compliance" ] } }, "/v1/compliance/attestation": { "get": { "description": "A per-tenant, externally-verifiable statement for the period: signed receipts produced for gateway-routed traffic, end-to-end chain verification, per-check coverage, enforcement actions, and packs in force — anchored by an RFC 6962 Merkle root over the receipts’ chain hashes (content-free). Scope is bounded to gateway-routed traffic; surface the `scope` and `disclaimer` verbatim. NOT a compliance certification.", "operationId": "ComplianceController_getAttestation", "parameters": [ { "name": "range", "required": false, "in": "query", "description": "Compact window, `Nd` or `Nh` (e.g. 30d, 24h).", "schema": { "example": "30d" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationDto" } } } }, "400": { "description": "Malformed `range` (must match `Nd` or `Nh`)" } }, "security": [ { "bearer": [] } ], "summary": "Regulator-ready live attestation over the receipt chain", "tags": [ "compliance" ] } }, "/v1/compliance/attestation/receipts/{id}/inclusion": { "get": { "description": "A content-free RFC 6962 audit path proving one receipt is committed by the period’s Merkle root — without revealing any other receipt or any prompt content. Verify it against the attestation’s `merkle.root`.", "operationId": "ComplianceController_getAttestationInclusion", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "receipt_id (UUID)", "schema": { "type": "string" } }, { "name": "range", "required": false, "in": "query", "description": "Same window as the attestation being verified.", "schema": { "example": "30d" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationInclusionDto" } } } }, "400": { "description": "Malformed receipt id or range" }, "404": { "description": "Receipt is not in the attested period" } }, "security": [ { "bearer": [] } ], "summary": "Inclusion proof that a receipt is committed by the attestation", "tags": [ "compliance" ] } }, "/health": { "get": { "operationId": "HealthController_check", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "Health" ] } }, "/status": { "get": { "operationId": "StatusController_get", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemStatusDto" } } } } }, "summary": "Public system status — request-path + dependency health", "tags": [ "status" ] } } }, "info": { "title": "Wardin API", "description": "AI governance & observability platform — external REST API", "version": "1.0", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "CreateKeyDto": { "type": "object", "properties": { "label": { "type": "string", "example": "CI pipeline key" }, "keyClass": { "type": "string", "enum": [ "interactive", "ci" ] }, "budgetUsd": { "type": "number", "example": 50, "description": "Monthly budget in USD" }, "rpmLimit": { "type": "number", "example": 60, "nullable": true, "description": "Max requests per minute. null or 0 = unlimited." }, "tpmLimit": { "type": "number", "example": 100000, "nullable": true, "description": "Max tokens per minute. null or 0 = unlimited." }, "ownerId": { "type": "string", "nullable": true, "description": "User who owns/uses this key. Must belong to the caller’s tenant. Omitted or null = ownerless (CI/service key)." }, "teamId": { "type": "string", "nullable": true, "description": "Cost-center team this key bills to. Must belong to the caller’s tenant. When omitted and ownerId is set, defaults to that owner’s current team. Explicit null = unassigned (no team)." } }, "required": [ "label", "keyClass", "budgetUsd" ] }, "UpdateKeyLimitsDto": { "type": "object", "properties": { "rpmLimit": { "type": "number", "example": 60, "nullable": true, "description": "Max requests per minute. null or 0 = unlimited." }, "tpmLimit": { "type": "number", "example": 100000, "nullable": true, "description": "Max tokens per minute. null or 0 = unlimited." } } }, "KeyLimitsResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "rpmLimit": { "type": "number", "example": 60, "nullable": true }, "tpmLimit": { "type": "number", "example": 100000, "nullable": true } }, "required": [ "id", "rpmLimit", "tpmLimit" ] }, "AssignKeyDto": { "type": "object", "properties": { "ownerId": { "type": "string", "nullable": true, "description": "User who owns/uses this key. Omit to leave unchanged; null clears ownership." }, "teamId": { "type": "string", "nullable": true, "description": "Cost-center team this key bills to. Omit to leave unchanged; null clears the assignment (falls back to owner’s team in the ledger rollup)." } } }, "AssignKeyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "ownerId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440001", "nullable": true }, "teamId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440002", "nullable": true } }, "required": [ "id", "ownerId", "teamId" ] }, "UpdateUserLimitDto": { "type": "object", "properties": { "allowedModels": { "example": [ "claude-sonnet-4-6" ], "type": "array", "items": { "type": "string" } }, "budgetCapUsd": { "type": "number", "example": 25, "nullable": true }, "status": { "type": "string", "enum": [ "active", "suspended" ] } } }, "UpdateBudgetDto": { "type": "object", "properties": { "budgetUsd": { "type": "number", "example": 100, "description": "New monthly budget in USD" } }, "required": [ "budgetUsd" ] }, "CreateBudgetRequestDto": { "type": "object", "properties": { "virtualKeyId": { "type": "string" }, "fromUsd": { "type": "number", "example": 20 }, "toUsd": { "type": "number", "example": 50 }, "reason": { "type": "string", "example": "Need more budget for Q2 analysis job" }, "durationHours": { "type": "number", "example": 24, "description": "How long (hours) the elevated budget is needed. On approve the budget auto-reverts after this window. Default 24, max 720." } }, "required": [ "virtualKeyId", "fromUsd", "toUsd", "reason" ] }, "CreatePolicyDto": { "type": "object", "properties": { "name": { "type": "string", "example": "PII Detection" }, "type": { "type": "string", "enum": [ "pii", "budget", "prompt_injection", "model_allowlist", "tool_allowlist" ] }, "enabled": { "type": "boolean", "default": true }, "yaml": { "type": "string", "example": "guardrail: pii\naction: redact" } }, "required": [ "name", "type", "enabled", "yaml" ] }, "UpdatePolicyDto": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "yaml": { "type": "string" } } }, "ReceiptCheckDto": { "type": "object", "properties": { "name": { "type": "string", "example": "policy" }, "result": { "type": "string", "example": "allow" } }, "required": [ "name", "result" ] }, "RecentReceiptEntryDto": { "type": "object", "properties": { "seq": { "type": "number", "example": 42 }, "receiptId": { "type": "string", "example": "018f1234-5678-7abc-def0-123456789abc" }, "requestId": { "type": "string", "example": "req-abc-123" }, "actor": { "type": "string", "example": "user@example.com" }, "provider": { "type": "string", "example": "anthropic" }, "model": { "type": "string", "example": "claude-3-5-sonnet-20241022" }, "promptTokens": { "type": "number", "example": 1000 }, "completionTokens": { "type": "number", "example": 250 }, "costUsd": { "type": "number", "example": 0.00375 }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptCheckDto" } }, "ts": { "type": "string", "example": "2026-07-02 12:00:00.000" }, "kind": { "type": "string", "enum": [ "model_call", "tool_call" ], "example": "model_call", "description": "COMPLY-4: distinguishes an agent tool-call receipt (gateway /mcp/tool-call or /mcp/servers — provider = MCP server, model = tool name) from a model-inference receipt. NOT part of the signed canonical receipt — an unsigned, queryable side channel. Rows written before this column existed read back as model_call." } }, "required": [ "seq", "receiptId", "requestId", "actor", "provider", "model", "promptTokens", "completionTokens", "costUsd", "checks", "ts", "kind" ] }, "RecentReceiptListDto": { "type": "object", "properties": { "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/RecentReceiptEntryDto" } }, "nextCursor": { "type": "number", "example": 40, "nullable": true, "description": "Seq of the last returned receipt — pass as `cursor` to fetch the next page. null when this is the last page." } }, "required": [ "receipts", "nextCursor" ] }, "ReceiptResponseDto": { "type": "object", "properties": { "seq": { "type": "number", "example": 42 }, "receiptId": { "type": "string", "example": "018f1234-5678-7abc-def0-123456789abc" }, "tenantId": { "type": "string", "example": "tenant-abc" }, "requestId": { "type": "string", "example": "req-abc-123" }, "actor": { "type": "string", "example": "user@example.com" }, "provider": { "type": "string", "example": "anthropic" }, "model": { "type": "string", "example": "claude-3-5-sonnet-20241022" }, "promptTokens": { "type": "number", "example": 1000 }, "completionTokens": { "type": "number", "example": 250 }, "costUsd": { "type": "number", "example": 0.00375 }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptCheckDto" } }, "prevHash": { "type": "string", "example": "a1b2c3..." }, "thisHash": { "type": "string", "example": "d4e5f6..." }, "signature": { "type": "string", "example": "base64-encoded-sig" }, "keyId": { "type": "string", "example": "key-id-1" }, "ts": { "type": "string", "example": "2026-07-02 12:00:00.000" }, "verified": { "type": "boolean", "example": true, "description": "True when this_hash == sha256(canonical || prev_hash) and the ED25519 signature is valid." }, "checkLatenciesMs": { "type": "object", "additionalProperties": { "type": "number" }, "example": { "AUTH": 2, "BUDGET": 5, "ALLOWLIST": 1, "GUARDRAIL": 8, "PII": 3 }, "description": "GW-12: per-check enforcement latency in milliseconds, keyed by check name. NOT part of the signed canonical receipt (EVID-1) — observability data only. Empty on receipts written before this column existed." }, "packVersion": { "type": "string", "example": "v1", "description": "COMPLY-1: the compliance pack-set version in force when this receipt was emitted (WARDIN_COMPLIANCE_PACK_VERSION). NOT part of the signed canonical receipt — an unsigned, queryable side channel. Empty string on receipts written before this column existed or with the env var unset." }, "kind": { "type": "string", "enum": [ "model_call", "tool_call" ], "example": "model_call", "description": "COMPLY-4: distinguishes an agent tool-call receipt (gateway /mcp/tool-call or /mcp/servers — provider = MCP server, model = tool name) from a model-inference receipt. NOT part of the signed canonical receipt — an unsigned, queryable side channel. Rows written before this column existed read back as model_call." } }, "required": [ "seq", "receiptId", "tenantId", "requestId", "actor", "provider", "model", "promptTokens", "completionTokens", "costUsd", "checks", "prevHash", "thisHash", "signature", "keyId", "ts", "verified", "checkLatenciesMs", "packVersion", "kind" ] }, "ChainVerifyResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "count": { "type": "number", "example": 100 }, "brokenAtSeq": { "type": "number", "example": 42, "description": "First seq whose hash does not match recomputed value." }, "gapAtSeq": { "type": "number", "example": 43, "description": "First non-contiguous seq." } }, "required": [ "ok", "count" ] }, "GithubLinkDto": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Wardin session id to attribute the PR outcome to" }, "pr": { "type": "string", "description": "PR identity as owner/repo#N", "example": "acme/widgets#123" }, "outcome": { "type": "string", "enum": [ "merged", "closed" ] } }, "required": [ "sessionId", "pr", "outcome" ] }, "TeamMemberDto": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "developer", "manager", "admin" ] }, "clerkUserId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "imageUrl": { "type": "string", "nullable": true }, "joinedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "email", "role", "clerkUserId", "name", "imageUrl", "joinedAt" ] }, "InviteMemberDto": { "type": "object", "properties": { "email": { "type": "string", "example": "dev@example.com" }, "role": { "type": "string", "enum": [ "developer", "manager", "admin" ], "default": "developer" } }, "required": [ "email", "role" ] }, "UpdateRoleDto": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "developer", "manager", "admin" ] } }, "required": [ "role" ] }, "TeamDto": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "budgetPoolUsd": { "type": "number", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "tenantId", "name", "budgetPoolUsd", "createdAt", "updatedAt" ] }, "CreateTeamDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Team name, unique within the tenant" }, "budgetPoolUsd": { "type": "number", "description": "Optional budget pool for the team in USD", "nullable": true } }, "required": [ "name" ] }, "RenameTeamDto": { "type": "object", "properties": { "name": { "type": "string", "description": "New team name, unique within the tenant" }, "budgetPoolUsd": { "type": "number", "description": "Optional budget pool for the team in USD", "nullable": true } }, "required": [ "name" ] }, "AssignUserDto": { "type": "object", "properties": { "teamId": { "type": "string", "description": "Team ID to assign the user to, or null to remove from team", "nullable": true } }, "required": [ "teamId" ] }, "CreateWebhookEndpointDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Slack #alerts", "description": "Human-readable name for this endpoint" }, "url": { "type": "string", "example": "https://hooks.slack.com/services/T00/B00/xxx", "description": "Destination URL for webhook delivery" }, "type": { "type": "string", "enum": [ "slack", "generic" ], "default": "generic", "description": "Payload format: slack uses the Slack incoming-webhook shape" }, "events": { "example": [ "budget.threshold_reached", "policy.violation" ], "description": "Event types this endpoint subscribes to", "type": "array", "items": { "type": "string" } } }, "required": [ "name", "url", "type", "events" ] }, "UpdateWebhookEndpointDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Slack #alerts", "description": "Human-readable name for this endpoint" }, "url": { "type": "string", "example": "https://hooks.slack.com/services/T00/B00/xxx", "description": "Destination URL for webhook delivery" }, "type": { "type": "string", "enum": [ "slack", "generic" ], "description": "Payload format: slack uses the Slack incoming-webhook shape" }, "events": { "example": [ "budget.threshold_reached", "policy.violation" ], "description": "Event types this endpoint subscribes to", "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean", "example": true, "description": "Enable or disable delivery to this endpoint" } } }, "UsageResponseDto": { "type": "object", "properties": { "plan": { "type": "string" }, "used": { "type": "number" }, "included": { "type": "number" }, "hardCap": { "type": "number" }, "overageEnabled": { "type": "boolean" }, "overage": { "type": "number" }, "blocked": { "type": "boolean" }, "status": { "type": "string" } }, "required": [ "plan", "used", "included", "hardCap", "overageEnabled", "overage", "blocked", "status" ] }, "CreateCheckoutDto": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "starter", "growth", "scale" ] }, "successUrl": { "type": "string", "description": "URL Stripe redirects to on success" }, "cancelUrl": { "type": "string", "description": "URL Stripe redirects to on cancel" } }, "required": [ "plan", "successUrl", "cancelUrl" ] }, "CreatePortalDto": { "type": "object", "properties": { "returnUrl": { "type": "string", "description": "URL the billing portal returns to" } }, "required": [ "returnUrl" ] }, "PromptDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Prompt UUID" }, "name": { "type": "string", "description": "Human-readable prompt name (unique per tenant)" }, "description": { "type": "string", "description": "Optional description" }, "labels": { "type": "object", "description": "Map of label name → version number (e.g. { production: 2 })", "additionalProperties": { "type": "number" } }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "description", "labels", "createdAt" ] }, "PromptVersionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Version UUID" }, "promptId": { "type": "string", "description": "Parent prompt UUID" }, "version": { "type": "number", "description": "Sequential version number (starts at 1)" }, "content": { "type": "string", "description": "Prompt text; supports {{variable}} placeholders" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "promptId", "version", "content", "createdAt" ] }, "CreatePromptDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Support reply template" }, "description": { "type": "string", "example": "Used by the support team for first-response drafts", "nullable": true }, "content": { "type": "string", "example": "You are a helpful support agent. Reply to: {{message}}" } }, "required": [ "name", "description", "content" ] }, "CreateVersionDto": { "type": "object", "properties": { "promptId": { "type": "string", "description": "Parent prompt UUID" }, "content": { "type": "string", "example": "Updated system prompt text" } }, "required": [ "promptId", "content" ] }, "SetLabelDto": { "type": "object", "properties": { "promptId": { "type": "string", "description": "Parent prompt UUID" }, "label": { "type": "string", "example": "production" }, "versionId": { "type": "string", "description": "Version UUID to point this label at" } }, "required": [ "promptId", "label", "versionId" ] }, "RunPromptDto": { "type": "object", "properties": { "promptId": { "type": "string", "description": "Parent prompt UUID" }, "versionId": { "type": "string", "description": "Version UUID to run" }, "variables": { "type": "object", "description": "Variable substitution map for {{key}} placeholders", "additionalProperties": { "type": "string" }, "nullable": true } }, "required": [ "promptId", "versionId", "variables" ] }, "RunResultDto": { "type": "object", "properties": { "output": { "type": "string", "description": "Model output text" }, "inputTokens": { "type": "number", "description": "Prompt tokens consumed (excl. cache tokens)" }, "outputTokens": { "type": "number", "description": "Completion tokens produced" }, "costUsd": { "type": "number", "description": "Estimated cost in USD" } }, "required": [ "output", "inputTokens", "outputTokens", "costUsd" ] }, "ResolvedLabelDto": { "type": "object", "properties": { "promptId": { "type": "string" }, "versionId": { "type": "string" }, "version": { "type": "number" }, "content": { "type": "string" } }, "required": [ "promptId", "versionId", "version", "content" ] }, "ProviderCredentialResponseDto": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "anthropic", "openai", "bedrock", "vertex", "openrouter" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "keyHint": { "type": "string", "description": "Last 4 characters of the primary secret, for display only", "example": "3456" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "provider", "status", "keyHint", "updatedAt" ] }, "UpsertProviderCredentialDto": { "type": "object", "properties": { "api_key": { "type": "string", "description": "anthropic | openai — the API key", "example": "sk-ant-..." }, "base_url": { "type": "string", "description": "anthropic | openai — optional custom base URL", "example": "https://api.anthropic.com" }, "access_key_id": { "type": "string", "description": "bedrock — AWS access key id" }, "secret_access_key": { "type": "string", "description": "bedrock — AWS secret access key" }, "region": { "type": "string", "description": "bedrock — AWS region, or vertex — optional GCP region", "example": "us-east-1" }, "service_account_json": { "type": "string", "description": "vertex — GCP service-account JSON, as a string" } } }, "ProviderTestResultDto": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "ok" ] }, "FrameworkSummaryDto": { "type": "object", "properties": { "framework": { "type": "string", "example": "eu_ai_act" }, "version": { "type": "string", "example": "v1" }, "title": { "type": "string", "example": "EU AI Act — automatic logging & deployer duties" }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "reviewed" ] }, "effectiveDate": { "type": "string", "example": "2026-07-09" }, "controlCount": { "type": "number", "example": 3 }, "packHash": { "type": "string", "example": "b7e1c2f4a8d6e0f3c1a9b5d7e2f4a6c8d0b2e4f6a8c0d2e4f6a8c0d2e4f6a8c0", "description": "sha256 of the pack’s raw YAML bytes." }, "source": { "type": "string", "example": "baseline", "enum": [ "baseline", "tenant" ], "description": "baseline = in-repo, counsel-reviewed pack; tenant = a BYO custom pack (COMPLY-7) — the tenant’s own DRAFT interpretation." } }, "required": [ "framework", "version", "title", "status", "effectiveDate", "controlCount", "packHash", "source" ] }, "FrameworkListDto": { "type": "object", "properties": { "frameworks": { "type": "array", "items": { "$ref": "#/components/schemas/FrameworkSummaryDto" } } }, "required": [ "frameworks" ] }, "CoverageSummaryDto": { "type": "object", "properties": { "enforced": { "type": "number", "example": 1 }, "partial": { "type": "number", "example": 2 }, "external": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 3 } }, "required": [ "enforced", "partial", "external", "total" ] }, "CoverageControlDto": { "type": "object", "properties": { "id": { "type": "string", "example": "eu_ai_act:art_12" }, "title": { "type": "string", "example": "Record-keeping — automatic logging of events" }, "coverage": { "type": "string", "example": "enforced", "enum": [ "enforced", "partial", "external" ], "description": "enforced = proven per-request on the enforcement path; partial = partially supported; external = you must document elsewhere." }, "provenBy": { "example": [ "ALLOWLIST", "GUARDRAIL", "UPSTREAM" ], "description": "Receipt checks that satisfy this control.", "type": "array", "items": { "type": "string" } }, "evidence": { "type": "string", "example": "Every gateway request emits a signed, hash-chained receipt recording the checks applied." }, "gap": { "type": "string", "nullable": true, "example": "Durable WORM retention remains your responsibility." } }, "required": [ "id", "title", "coverage", "provenBy", "evidence" ] }, "CoverageMapDto": { "type": "object", "properties": { "framework": { "type": "string", "example": "eu_ai_act" }, "version": { "type": "string", "example": "v1" }, "title": { "type": "string", "example": "EU AI Act — automatic logging & deployer duties" }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "reviewed" ] }, "effectiveDate": { "type": "string", "example": "2026-07-09" }, "disclaimer": { "type": "string", "description": "Legal-posture disclaimer — surface verbatim. Not legal advice; scope is gateway-routed traffic." }, "packHash": { "type": "string", "example": "b7e1c2f4a8d6e0f3c1a9b5d7e2f4a6c8d0b2e4f6a8c0d2e4f6a8c0d2e4f6a8c0", "description": "sha256 of the pack’s raw YAML bytes." }, "source": { "type": "string", "example": "baseline", "enum": [ "baseline", "tenant" ], "description": "baseline (in-repo) or tenant (BYO custom pack, COMPLY-7)." }, "summary": { "$ref": "#/components/schemas/CoverageSummaryDto" }, "controls": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageControlDto" } } }, "required": [ "framework", "version", "title", "status", "effectiveDate", "disclaimer", "packHash", "source", "summary", "controls" ] }, "ReceiptControlDto": { "type": "object", "properties": { "id": { "type": "string", "example": "eu_ai_act:art_12" }, "title": { "type": "string", "example": "Record-keeping — automatic logging of events" }, "coverage": { "type": "string", "example": "enforced" }, "check": { "type": "string", "example": "GUARDRAIL", "description": "The receipt check that was applied and recorded on this request." }, "result": { "type": "string", "example": "PASS", "description": "The recorded result of that check (a FAIL is still Art-12-grade evidence of enforcement)." } }, "required": [ "id", "title", "coverage", "check", "result" ] }, "ReceiptFrameworkControlsDto": { "type": "object", "properties": { "framework": { "type": "string", "example": "eu_ai_act" }, "version": { "type": "string", "nullable": true, "example": "v1" }, "disclaimer": { "type": "string", "nullable": true }, "packHash": { "type": "string", "nullable": true, "example": "b7e1c2f4a8d6e0f3c1a9b5d7e2f4a6c8d0b2e4f6a8c0d2e4f6a8c0d2e4f6a8c0", "description": "sha256 of the raw YAML bytes of the pack the controls were cited from." }, "resolution": { "type": "string", "example": "stamped", "enum": [ "stamped", "fallback_in_force", "unstamped" ], "description": "How this framework’s pack was resolved for the receipt: stamped = the receipt’s stamped pack_version resolved to a known pack (controls cited from it); fallback_in_force = a non-empty stamp did not resolve (deploy skew) so the current in-force pack was used and flagged; unstamped = no stamp (old receipt or env unset) → in-force pack." }, "controls": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptControlDto" } } }, "required": [ "framework", "resolution", "controls" ] }, "ReceiptControlsDto": { "type": "object", "properties": { "receiptId": { "type": "string", "example": "018f1234-5678-7abc-def0-123456789abc" }, "receiptPackVersion": { "type": "string", "example": "v1", "description": "The compliance pack-set version stamped on the receipt at emit time (unsigned side channel). Empty string when unstamped (old receipt or WARDIN_COMPLIANCE_PACK_VERSION unset). Per-framework `resolution` says whether this stamp resolved to a known pack." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptCheckDto" } }, "verified": { "type": "boolean", "example": true, "description": "Whether the receipt’s ED25519 signature cryptographically verified." }, "note": { "type": "string", "nullable": true, "example": null, "description": "Caveat surfaced when verified is false; null when the receipt verified." }, "frameworks": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptFrameworkControlsDto" } } }, "required": [ "receiptId", "receiptPackVersion", "checks", "verified", "frameworks" ] }, "ControlReceiptSummaryDto": { "type": "object", "properties": { "total": { "type": "number", "example": 42, "description": "Accurate count over the ENTIRE window — a separate aggregate query, not a count of the (possibly capped) returned rows. total = enforced + failed + indeterminate." }, "enforced": { "type": "number", "example": 40, "description": "Every proving check resulted in PASS, BLOCKED, or REDACTED — the control ran in-path and functioned (allow or act are both governance evidence). Derived as total - failed - indeterminate." }, "failed": { "type": "number", "example": 2, "description": "At least one proving check recorded a technical/upstream failure (FAIL::)." }, "indeterminate": { "type": "number", "example": 0, "description": "No FAIL, but at least one proving check recorded a result outside {PASS, BLOCKED, REDACTED, FAIL:*} — an unrecognized result — or a receipt had no proving checks at all. Never assumed enforced." } }, "required": [ "total", "enforced", "failed", "indeterminate" ] }, "ControlReceiptRowDto": { "type": "object", "properties": { "receiptId": { "type": "string", "example": "018f1234-5678-7abc-def0-123456789abc" }, "seq": { "type": "number", "example": 4821 }, "ts": { "type": "string", "example": "2026-07-09 12:34:56.789" }, "actor": { "type": "string", "example": "key-1" }, "provider": { "type": "string", "example": "anthropic" }, "model": { "type": "string", "example": "claude-3-5-haiku-20241022" }, "outcome": { "type": "string", "example": "enforced", "enum": [ "enforced", "failed", "indeterminate" ], "description": "A receipt matches if AT LEAST ONE of the control’s proving checks was applied; per-row `provingChecks` shows which ran. enforced = every proving check resulted in PASS, BLOCKED, or REDACTED (ran in-path and functioned; allow or act are both governance evidence). failed = a proving check recorded a technical/upstream failure (FAIL::). indeterminate = a proving check recorded an unrecognized result, or none of this control’s proving checks were present on the row — never assumed enforced." }, "provingChecks": { "description": "The subset of this receipt’s checks that prove the control.", "type": "array", "items": { "$ref": "#/components/schemas/ReceiptCheckDto" } }, "packVersion": { "type": "string", "example": "v1", "nullable": true, "description": "COMPLY-1: the compliance pack-set version in force when this receipt was emitted. NOT part of the signed canonical receipt — an unsigned, queryable side channel. Empty string when unstamped (receipts written before this column existed, or with the env var unset)." } }, "required": [ "receiptId", "seq", "ts", "actor", "provider", "model", "outcome", "provingChecks", "packVersion" ] }, "ControlReceiptsDto": { "type": "object", "properties": { "framework": { "type": "string", "example": "eu_ai_act" }, "controlId": { "type": "string", "example": "eu_ai_act:art_12" }, "controlTitle": { "type": "string", "example": "Record-keeping — automatic logging of events" }, "coverage": { "type": "string", "example": "enforced", "enum": [ "enforced", "partial", "external" ] }, "packVersion": { "type": "string", "example": "v1" }, "packHash": { "type": "string", "example": "b7e1c2f4a8d6e0f3c1a9b5d7e2f4a6c8d0b2e4f6a8c0d2e4f6a8c0d2e4f6a8c0", "description": "sha256 of the pack’s raw YAML bytes." }, "disclaimer": { "type": "string", "description": "Legal-posture disclaimer — surface verbatim. Not legal advice; scope is gateway-routed traffic." }, "source": { "type": "string", "example": "baseline", "enum": [ "baseline", "tenant" ], "description": "baseline (in-repo) or tenant (BYO custom pack, COMPLY-7)." }, "range": { "type": "string", "example": "7d" }, "days": { "type": "number", "example": 7 }, "provenBy": { "example": [ "GUARDRAIL" ], "description": "Receipt checks that prove this control.", "type": "array", "items": { "type": "string" } }, "limit": { "type": "number", "example": 100, "description": "The effective (clamped) page size used for `receipts`, 1..500." }, "truncated": { "type": "boolean", "example": true, "description": "True when `receipts` did not reach the end of the window — more rows exist. Page with `nextCursor`." }, "nextCursor": { "type": "number", "nullable": true, "example": 4821, "description": "seq of the last row in this page — pass as `cursor` to fetch the next page. null when there are no more rows." }, "summary": { "description": "Accurate counts over the whole window — not just the returned sample below.", "allOf": [ { "$ref": "#/components/schemas/ControlReceiptSummaryDto" } ] }, "receipts": { "description": "A sample (page) of up to `limit` rows, ordered by seq DESC — not the full window. Use `nextCursor` to page through the rest.", "type": "array", "items": { "$ref": "#/components/schemas/ControlReceiptRowDto" } } }, "required": [ "framework", "controlId", "controlTitle", "coverage", "packVersion", "packHash", "disclaimer", "source", "range", "days", "provenBy", "limit", "truncated", "summary", "receipts" ] }, "BundleRangeDto": { "type": "object", "properties": { "label": { "type": "string", "example": "30d" }, "days": { "type": "number", "example": 30 }, "fromSeq": { "type": "number", "nullable": true, "example": 1 }, "toSeq": { "type": "number", "nullable": true, "example": 4821 }, "fromTs": { "type": "string", "nullable": true }, "toTs": { "type": "string", "nullable": true }, "receiptCount": { "type": "number", "example": 4821 } }, "required": [ "label", "days", "receiptCount" ] }, "BundleAnchorDto": { "type": "object", "properties": { "type": { "type": "string", "example": "trusted_first_prev_hash" }, "prevHash": { "type": "string", "nullable": true, "description": "Starting prev_hash the verifier trusts (hex). Empty string for the true-genesis receipt (seq 1). COMPLY-5 replaces this with a signed root." }, "note": { "type": "string" } }, "required": [ "type", "note" ] }, "BundleKeyDto": { "type": "object", "properties": { "keyId": { "type": "string", "example": "wardin-2026-07" }, "publicKey": { "type": "string", "description": "base64 raw 32-byte ed25519 public key." }, "validFrom": { "type": "string", "nullable": true }, "validTo": { "type": "string", "nullable": true, "description": "null = currently active signing key." }, "revokedAt": { "type": "string", "nullable": true, "description": "Informational — a revoked/rotated key still verifies the historical receipts it signed." } }, "required": [ "keyId", "publicKey" ] }, "BundlePackDto": { "type": "object", "properties": { "framework": { "type": "string", "example": "eu_ai_act" }, "version": { "type": "string", "example": "v1" }, "title": { "type": "string", "example": "EU AI Act — automatic logging & deployer duties" }, "status": { "type": "string", "example": "draft" }, "effectiveDate": { "type": "string", "example": "2026-07-09" }, "packHash": { "type": "string", "description": "sha256 of the pack’s raw YAML bytes." }, "disclaimer": { "type": "string" }, "source": { "type": "string", "example": "baseline", "enum": [ "baseline", "tenant" ], "description": "baseline (in-repo) or tenant (BYO custom pack, COMPLY-7)." }, "rawYaml": { "type": "string", "nullable": true, "description": "The exact raw YAML bytes for a tenant-authored pack — snapshotted so a DB-authored mapping is reproducible offline. null for baseline packs (reproducible from git by packHash)." } }, "required": [ "framework", "version", "title", "status", "effectiveDate", "packHash", "disclaimer", "source" ] }, "BundleTenantPackDto": { "type": "object", "properties": { "framework": { "type": "string", "example": "my_framework" }, "version": { "type": "string", "example": "v1" }, "effectiveDate": { "type": "string", "example": "2026-01-01" }, "packHash": { "type": "string", "example": "a1b2c3…", "description": "sha256 of the raw YAML bytes." }, "status": { "type": "string", "example": "active", "enum": [ "active", "archived" ] }, "rawYaml": { "type": "string", "description": "The exact raw YAML bytes (reproducibility)." } }, "required": [ "framework", "version", "effectiveDate", "packHash", "status", "rawYaml" ] }, "BundleReceiptDto": { "type": "object", "properties": { "seq": { "type": "number", "example": 4821 }, "receiptId": { "type": "string", "example": "018f1234-5678-7abc-def0-123456789abc" }, "requestId": { "type": "string" }, "tenantId": { "type": "string" }, "actor": { "type": "string", "example": "key-1" }, "provider": { "type": "string", "example": "anthropic" }, "model": { "type": "string", "example": "claude-3-5-haiku-20241022" }, "promptTokens": { "type": "number", "example": 1200 }, "completionTokens": { "type": "number", "example": 340 }, "costUsd": { "type": "number", "example": 0.0042 }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptCheckDto" } }, "tsMillis": { "type": "number", "example": 1752062096789, "description": "Receipt timestamp as epoch milliseconds (UTC)." }, "prevHash": { "type": "string", "description": "prev_hash (hex); empty for genesis." }, "thisHash": { "type": "string", "description": "this_hash (hex)." }, "signature": { "type": "string", "description": "base64 ED25519 signature over this_hash." }, "keyId": { "type": "string" }, "packVersion": { "type": "string", "example": "v1", "description": "Compliance pack-set version in force." }, "kind": { "type": "string", "enum": [ "model_call", "tool_call" ], "example": "model_call", "description": "model_call | tool_call (COMPLY-4) — unsigned side channel, NOT part of the signed canonical receipt; ignored by offline verification." } }, "required": [ "seq", "receiptId", "requestId", "tenantId", "actor", "provider", "model", "promptTokens", "completionTokens", "costUsd", "checks", "tsMillis", "prevHash", "thisHash", "signature", "keyId", "packVersion", "kind" ] }, "EvidenceBundleDto": { "type": "object", "properties": { "bundleVersion": { "type": "string", "example": "1" }, "generatedAt": { "type": "string" }, "tenantId": { "type": "string" }, "range": { "$ref": "#/components/schemas/BundleRangeDto" }, "anchor": { "$ref": "#/components/schemas/BundleAnchorDto" }, "signingKeys": { "description": "Signing-key registry (EVID-6) for every key_id the receipts reference — so verification survives key rotation without a live endpoint.", "type": "array", "items": { "$ref": "#/components/schemas/BundleKeyDto" } }, "unresolvedKeyIds": { "description": "key_ids referenced by receipts that could NOT be resolved to a public key — their receipts will verify as unverifiable. Empty when complete.", "type": "array", "items": { "type": "string" } }, "packs": { "type": "array", "items": { "$ref": "#/components/schemas/BundlePackDto" } }, "tenantPacks": { "description": "The tenant’s complete custom-pack archive (active + archived) with raw YAML bytes — so any tenant-authored citation in the window is reproducible offline (there is no git copy for these).", "type": "array", "items": { "$ref": "#/components/schemas/BundleTenantPackDto" } }, "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/BundleReceiptDto" } }, "disclaimer": { "type": "string", "description": "Honesty posture — surface verbatim." } }, "required": [ "bundleVersion", "generatedAt", "tenantId", "range", "anchor", "signingKeys", "unresolvedKeyIds", "packs", "tenantPacks", "receipts", "disclaimer" ] }, "AttestationPeriodDto": { "type": "object", "properties": { "label": { "type": "string", "example": "30d" }, "days": { "type": "number", "example": 30 }, "fromSeq": { "type": "number", "nullable": true, "example": 1 }, "toSeq": { "type": "number", "nullable": true, "example": 4210 }, "fromTs": { "type": "string", "nullable": true, "example": "2026-06-10T00:00:00.000Z" }, "toTs": { "type": "string", "nullable": true, "example": "2026-07-10T00:00:00.000Z" } }, "required": [ "label", "days", "fromSeq", "toSeq", "fromTs", "toTs" ] }, "AttestationTotalsDto": { "type": "object", "properties": { "receipts": { "type": "number", "example": 4210, "description": "Signed receipts in the period." }, "modelReceipts": { "type": "number", "example": 4180, "description": "model_call receipts in the period. Per-check coverage for model checks (BUDGET/GUARDRAIL/ALLOWLIST) is relative to this, not the total (AGOV-6)." }, "toolReceipts": { "type": "number", "example": 30, "description": "tool_call receipts (agent governance). Per-check coverage for tool checks (AGENT_IDENTITY/TOOL_ALLOWLIST) is relative to this, not the total." }, "chainVerified": { "type": "boolean", "example": true, "description": "Whether the chain recomputed + verified end-to-end across the seq range with no gap or broken hash." }, "chainVerifiedCount": { "type": "number", "example": 4210 }, "signaturesVerified": { "type": "boolean", "example": true, "description": "Whether every receipt’s ED25519 signature verified against the signing-key registry." }, "signaturesVerifiedCount": { "type": "number", "example": 4210 }, "policyEvaluated": { "type": "number", "example": 4210, "description": "Receipts carrying ≥1 signed in-path check record." }, "policyEvaluatedPct": { "type": "number", "nullable": true, "example": 100 }, "enforcementActions": { "type": "number", "example": 37, "description": "Receipts where an in-path check blocked or redacted." }, "upstreamFailures": { "type": "number", "example": 5, "description": "Receipts with a technical/upstream FAIL on a check." } }, "required": [ "receipts", "modelReceipts", "toolReceipts", "chainVerified", "chainVerifiedCount", "signaturesVerified", "signaturesVerifiedCount", "policyEvaluated", "policyEvaluatedPct", "enforcementActions", "upstreamFailures" ] }, "AttestationCheckCoverageDto": { "type": "object", "properties": { "name": { "type": "string", "example": "GUARDRAIL" }, "receipts": { "type": "number", "example": 4210, "description": "Receipts carrying this check." }, "applicableReceipts": { "type": "number", "example": 4210, "description": "Receipts that COULD carry this check — the denominator `pct` is relative to (AGOV-6). Model checks → modelReceipts, tool checks → toolReceipts, UPSTREAM → all receipts. Makes the coverage figure self-describing." }, "pct": { "type": "number", "nullable": true, "example": 100, "description": "`receipts / applicableReceipts`, floored (never rounded up)." } }, "required": [ "name", "receipts", "applicableReceipts", "pct" ] }, "AttestationPackDto": { "type": "object", "properties": { "framework": { "type": "string", "example": "eu_ai_act" }, "version": { "type": "string", "example": "v1" }, "status": { "type": "string", "example": "draft" }, "packHash": { "type": "string", "example": "a1b2c3…" }, "source": { "type": "string", "example": "baseline", "enum": [ "baseline", "tenant" ], "description": "baseline (in-repo) or tenant (BYO custom pack, COMPLY-7)." } }, "required": [ "framework", "version", "status", "packHash", "source" ] }, "AttestationMerkleDto": { "type": "object", "properties": { "algorithm": { "type": "string", "example": "RFC6962-SHA256" }, "leafCount": { "type": "number", "example": 4210 }, "root": { "type": "string", "example": "9f2c…", "description": "Hex RFC 6962 Merkle root over the receipts’ chain hashes." } }, "required": [ "algorithm", "leafCount", "root" ] }, "AttestationAnchorDto": { "type": "object", "properties": { "type": { "type": "string", "example": "merkle_root_v1" }, "root": { "type": "string", "example": "9f2c…" }, "note": { "type": "string", "description": "How to verify the root; surface verbatim." } }, "required": [ "type", "root", "note" ] }, "AttestationDto": { "type": "object", "properties": { "version": { "type": "string", "example": "1" }, "tenantId": { "type": "string", "example": "018f1234-5678-7abc-def0-123456789abc" }, "generatedAt": { "type": "string", "example": "2026-07-10T12:00:00.000Z" }, "scope": { "type": "string", "description": "Exact, provable scope statement — surface verbatim." }, "disclaimer": { "type": "string", "description": "Honesty posture — surface verbatim." }, "period": { "$ref": "#/components/schemas/AttestationPeriodDto" }, "totals": { "$ref": "#/components/schemas/AttestationTotalsDto" }, "checkCoverage": { "type": "array", "items": { "$ref": "#/components/schemas/AttestationCheckCoverageDto" } }, "packsInForce": { "type": "array", "items": { "$ref": "#/components/schemas/AttestationPackDto" } }, "packVersionsObserved": { "example": [ "v1" ], "type": "array", "items": { "type": "string" } }, "signingKeyIds": { "description": "Signing key_ids that produced receipts in the period.", "type": "array", "items": { "type": "string" } }, "merkle": { "$ref": "#/components/schemas/AttestationMerkleDto" }, "anchor": { "$ref": "#/components/schemas/AttestationAnchorDto" } }, "required": [ "version", "tenantId", "generatedAt", "scope", "disclaimer", "period", "totals", "checkCoverage", "packsInForce", "packVersionsObserved", "signingKeyIds", "merkle", "anchor" ] }, "AttestationInclusionDto": { "type": "object", "properties": { "receiptId": { "type": "string", "example": "018f1234-5678-7abc-def0-123456789abc" }, "thisHash": { "type": "string", "example": "9f2c…", "description": "The receipt’s chain hash (Merkle leaf)." }, "seq": { "type": "number", "example": 4210 }, "index": { "type": "number", "example": 12, "description": "Leaf position in the period (0-based)." }, "treeSize": { "type": "number", "example": 4210 }, "algorithm": { "type": "string", "example": "RFC6962-SHA256" }, "proof": { "description": "RFC 6962 audit path (hex sibling hashes, bottom-up).", "type": "array", "items": { "type": "string" } }, "root": { "type": "string", "example": "9f2c…" }, "verified": { "type": "boolean", "example": true, "description": "Server-side recomputation of the proof against the root." } }, "required": [ "receiptId", "thisHash", "seq", "index", "treeSize", "algorithm", "proof", "root", "verified" ] }, "StatusComponentDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Gateway" }, "group": { "type": "string", "enum": [ "Core", "Data", "Communication", "Integrations" ], "example": "Core" }, "status": { "type": "string", "enum": [ "operational", "degraded", "down", "unknown" ], "example": "operational" }, "critical": { "type": "boolean", "description": "Customer-impact weight. A critical component down = major outage; a non-critical one down only degrades (e.g. stale dashboards)." }, "detail": { "type": "string", "description": "Optional sub-label, e.g. the underlying vendor.", "example": "ClickHouse" } }, "required": [ "name", "group", "status", "critical" ] }, "SystemStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "down", "unknown" ], "description": "Roll-up across all components, weighted by customer impact.", "example": "operational" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/StatusComponentDto" } }, "updatedAt": { "type": "string", "description": "RFC3339 timestamp of this snapshot." } }, "required": [ "status", "components", "updatedAt" ] } } } }