{ "components": { "schemas": { "ApiError": { "description": "Every failure on the public API uses this shape. `code` is stable and safe to branch on; `message` is written for a person and may be reworded.", "properties": { "error": { "properties": { "code": { "description": "The stable, machine-readable half of the failure.", "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "api_key_not_bound_to_agent", "api_key_not_organization_scoped", "api_key_not_permitted", "invalid_token", "connection_unauthorized", "insufficient_scope", "oauth_not_permitted", "organization_suspended", "unsupported_media_type", "malformed_json", "payload_too_large", "invalid_request", "not_found", "policy_name_taken", "policy_lifecycle_conflict", "budget_reconciliation_inconsistent", "draft_invalid", "idempotency_key_reuse", "webhook_url_not_permitted", "webhook_endpoint_revoked", "webhook_limit_reached", "webhook_not_configured", "internal_error" ], "type": "string" }, "issues": { "description": "Present only for `invalid_request` and `draft_invalid`. Carries every problem found, not just the first.", "items": { "$ref": "#/components/schemas/ErrorIssue" }, "type": "array" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "Currency": { "description": "An ISO 4217 alpha-3 currency code.", "examples": [ "GBP" ], "pattern": "^[A-Z]{3}$", "type": "string" }, "Decision": { "description": "What the Trust Engine decided, and why. A REJECTED decision is a successful call: Veriticity was asked a question and answered it.", "properties": { "engineVersion": { "examples": [ "veriticity-trust-engine@0.1.0" ], "type": "string" }, "evaluatedAt": { "$ref": "#/components/schemas/Timestamp" }, "explanation": { "description": "The sentence a person reads. Not a stable contract.", "type": "string" }, "id": { "$ref": "#/components/schemas/UUID" }, "outcome": { "description": "Branch on this, never on the HTTP status code.", "enum": [ "APPROVED", "REJECTED", "REQUIRES_APPROVAL" ], "type": "string" }, "reasonCodes": { "items": { "enum": [ "WITHIN_POLICY", "MERCHANT_BLOCKED", "MERCHANT_NOT_ALLOW_LISTED", "AMOUNT_EXCEEDS_MAX", "APPROVAL_THRESHOLD_EXCEEDED", "DAILY_LIMIT_EXCEEDED", "MONTHLY_LIMIT_EXCEEDED", "AGENT_DISABLED", "NO_APPLICABLE_POLICY", "CURRENCY_NOT_COVERED", "POLICY_CHANGED_SINCE_ESCALATION" ], "type": "string" }, "type": "array" } }, "required": [ "id", "outcome", "reasonCodes", "explanation", "evaluatedAt", "engineVersion" ], "type": "object" }, "DeliverableWebhookEventType": { "description": "Any event type that can arrive at an endpoint: the subscribable types plus `webhook.test`, which is delivered on request regardless of what the endpoint subscribes to.", "enum": [ "purchase.approval_required", "purchase.approved", "purchase.rejected", "purchase.approval_expired", "budget.threshold_reached", "budget.exhausted", "agent.disabled", "agent.archived", "connection.created", "connection.revoked", "security.connection_token_reuse_detected", "webhook.test" ], "type": "string" }, "ErrorIssue": { "properties": { "code": { "description": "A stable, machine-readable code for this one problem.", "examples": [ "AMOUNT_NOT_POSITIVE" ], "type": "string" }, "message": { "type": "string" }, "path": { "description": "The field at fault, named as the caller sent it. An empty string or \"body\" means the body as a whole.", "examples": [ "amountMinor" ], "type": "string" } }, "required": [ "path", "code", "message" ], "type": "object" }, "IssuedWebhookEndpoint": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "properties": { "secret": { "description": "The signing secret, shown exactly once. Veriticity cannot show it again. Store it before you close the response.", "pattern": "^cmp_whs_[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "secret" ], "type": "object" } ], "description": "An endpoint plus its signing secret. Returned only by creation and rotation; no read path can produce one." }, "MinorAmount": { "description": "A whole number of ISO 4217 minor units, as a decimal string. \"7500\" is GBP 75.00. A string rather than a number because JSON numbers are doubles and lose integer precision above 2^53, and this is money.", "examples": [ "7500" ], "pattern": "^-?\\d+$", "type": "string" }, "Pagination": { "description": "Where this page sits in the collection. Always present, including for a single short page, so a client needs only one rendering path.", "properties": { "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "description": "At least 1 even when nothing matched, so a client can render \"1 of 1\" for an empty result and never divide by zero.", "minimum": 1, "type": "integer" } }, "required": [ "page", "pageSize", "total", "totalPages" ], "type": "object" }, "PolicyIssue": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "PolicyMerchantEntry": { "description": "One merchant on a version's allow or block list.", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "label": { "description": "The merchant as a person wrote it.", "type": "string" }, "listType": { "enum": [ "ALLOW", "BLOCK" ], "type": "string" }, "merchantKey": { "description": "The normalised form the engine matches on. Veriticity derives it from the label; it is never supplied directly.", "type": "string" } }, "required": [ "id", "listType", "merchantKey", "label" ], "type": "object" }, "PolicyRule": { "description": "One limit or threshold inside a policy version.", "properties": { "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "currency": { "oneOf": [ { "$ref": "#/components/schemas/Currency" }, { "type": "null" } ] }, "effect": { "description": "BLOCK refuses outright. REQUIRE_APPROVAL holds the budget and waits for a person.", "enum": [ "BLOCK", "REQUIRE_APPROVAL" ], "type": "string" }, "id": { "$ref": "#/components/schemas/UUID" }, "periodKind": { "description": "PER_REQUEST for a single-purchase cap; DAY or MONTH for a window, resolved against the organisation's own timezone.", "enum": [ "PER_REQUEST", "DAY", "MONTH" ], "type": "string" }, "ruleType": { "description": "AMOUNT_LIMIT caps a single purchase. SPEND_LIMIT caps the total across a period.", "enum": [ "AMOUNT_LIMIT", "SPEND_LIMIT" ], "type": "string" } }, "required": [ "id", "ruleType", "effect", "periodKind", "amountMinor" ], "type": "object" }, "PolicySummary": { "properties": { "activeVersion": { "oneOf": [ { "$ref": "#/components/schemas/PolicyVersionSummary" }, { "type": "null" } ] }, "archivedAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/UUID" }, "inForce": { "description": "Whether the Trust Engine is actually reading this policy right now. \"Has a live version\" and \"is being enforced\" are different facts: a DISABLED policy keeps its ACTIVE version but the engine skips it.", "type": "boolean" }, "name": { "type": "string" }, "scopeType": { "enum": [ "ORGANIZATION", "AGENT" ], "type": "string" }, "status": { "enum": [ "ACTIVE", "DISABLED", "ARCHIVED" ], "type": "string" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "id", "name", "scopeType", "status", "inForce", "createdAt", "updatedAt", "activeVersion" ], "type": "object" }, "PolicyVersion": { "allOf": [ { "$ref": "#/components/schemas/PolicyVersionSummary" }, { "properties": { "merchants": { "items": { "$ref": "#/components/schemas/PolicyMerchantEntry" }, "type": "array" }, "policyId": { "$ref": "#/components/schemas/UUID" }, "rules": { "items": { "$ref": "#/components/schemas/PolicyRule" }, "type": "array" } }, "required": [ "policyId", "rules", "merchants" ], "type": "object" } ], "description": "A policy version in full, including its rules and merchant lists, exactly as the Trust Engine reads it." }, "PolicyVersionSummary": { "properties": { "activatedAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "archivedAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "currencies": { "description": "The currencies this version covers. A purchase in any other currency is refused with CURRENCY_NOT_COVERED: Veriticity performs no currency conversion.", "items": { "$ref": "#/components/schemas/Currency" }, "type": "array" }, "currencyScope": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/UUID" }, "merchantCount": { "description": "How many merchant entries this version carries.", "minimum": 0, "type": "integer" }, "ruleCount": { "description": "How many rules this version carries, without fetching them.", "minimum": 0, "type": "integer" }, "status": { "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ], "type": "string" }, "versionNumber": { "description": "Allocated by Veriticity. Never chosen by a caller.", "minimum": 1, "type": "integer" } }, "required": [ "id", "versionNumber", "status", "currencies", "ruleCount", "merchantCount", "createdAt" ], "type": "object" }, "PurchaseDecisionResponse": { "properties": { "approval": { "description": "Whether a person still has to answer, and by when. The budget hold behind an escalation is released when the approval lapses.", "properties": { "expiresAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "required": { "type": "boolean" } }, "required": [ "required", "expiresAt" ], "type": "object" }, "decision": { "$ref": "#/components/schemas/Decision" }, "policyVersions": { "items": { "properties": { "applicabilityReason": { "type": "string" }, "policyVersionId": { "$ref": "#/components/schemas/UUID" } }, "required": [ "policyVersionId", "applicabilityReason" ], "type": "object" }, "type": "array" }, "purchaseRequest": { "$ref": "#/components/schemas/PurchaseRequestSummary" }, "replayed": { "description": "True when this is the stored answer to an earlier identical request. The decision is real and binding either way; what differs is that no new budget was reserved.", "type": "boolean" }, "ruleEvaluations": { "items": { "$ref": "#/components/schemas/RuleEvaluation" }, "type": "array" } }, "required": [ "purchaseRequest", "decision", "approval", "policyVersions", "ruleEvaluations", "replayed" ], "type": "object" }, "PurchaseReadback": { "description": "A purchase as the credential that submitted it may see it afterwards.", "properties": { "agent": { "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "status": { "enum": [ "ENABLED", "DISABLED", "ARCHIVED" ], "type": "string" } }, "required": [ "id", "name", "status" ], "type": "object" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "approval": { "oneOf": [ { "description": "The escalation, if the purchase needed one. Null means no person was ever asked, which is a different thing from an approval that is pending.", "properties": { "comment": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "escalationReasonCodes": { "items": { "enum": [ "WITHIN_POLICY", "MERCHANT_BLOCKED", "MERCHANT_NOT_ALLOW_LISTED", "AMOUNT_EXCEEDS_MAX", "APPROVAL_THRESHOLD_EXCEEDED", "DAILY_LIMIT_EXCEEDED", "MONTHLY_LIMIT_EXCEEDED", "AGENT_DISABLED", "NO_APPLICABLE_POLICY", "CURRENCY_NOT_COVERED", "POLICY_CHANGED_SINCE_ESCALATION" ], "type": "string" }, "type": "array" }, "expiresAt": { "$ref": "#/components/schemas/Timestamp" }, "isPending": { "type": "boolean" }, "resolvedAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "resolvedBy": { "oneOf": [ { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, { "type": "null" } ] }, "state": { "enum": [ "PENDING", "APPROVED", "REJECTED", "EXPIRED", "CANCELLED" ], "type": "string" } }, "required": [ "state", "isPending", "escalationReasonCodes", "expiresAt", "resolvedAt", "resolvedBy", "comment" ], "type": "object" }, { "type": "null" } ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "decision": { "oneOf": [ { "properties": { "engineVersion": { "type": "string" }, "evaluatedAt": { "$ref": "#/components/schemas/Timestamp" }, "explanation": { "type": "string" }, "kind": { "description": "INITIAL, or APPROVAL_REEVALUATION once a person answered.", "type": "string" }, "outcome": { "enum": [ "APPROVED", "REJECTED", "REQUIRES_APPROVAL" ], "type": "string" }, "reasonCodes": { "items": { "enum": [ "WITHIN_POLICY", "MERCHANT_BLOCKED", "MERCHANT_NOT_ALLOW_LISTED", "AMOUNT_EXCEEDS_MAX", "APPROVAL_THRESHOLD_EXCEEDED", "DAILY_LIMIT_EXCEEDED", "MONTHLY_LIMIT_EXCEEDED", "AGENT_DISABLED", "NO_APPLICABLE_POLICY", "CURRENCY_NOT_COVERED", "POLICY_CHANGED_SINCE_ESCALATION" ], "type": "string" }, "type": "array" } }, "required": [ "outcome", "reasonCodes", "explanation", "evaluatedAt", "kind", "engineVersion" ], "type": "object" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/UUID" }, "initiatedBy": { "oneOf": [ { "description": "The person who raised it, for a dashboard purchase. Null for every machine origin: an API key and a connection were used by software.", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, { "type": "null" } ] }, "merchant": { "type": "string" }, "merchantDomain": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "origin": { "oneOf": [ { "description": "Which surface the purchase arrived on. Null for purchases written before origin was recorded. Never inferred from the credential.", "enum": [ "DASHBOARD", "API", "MCP" ], "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "requestedAt": { "$ref": "#/components/schemas/Timestamp" }, "resolvedAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "status": { "enum": [ "EVALUATING", "PENDING_APPROVAL", "APPROVED", "REJECTED", "EXPIRED", "CANCELLED" ], "type": "string" }, "submittedVia": { "oneOf": [ { "oneOf": [ { "properties": { "apiKeyPrefix": { "description": "The public half of the key. Never the secret.", "type": "string" }, "type": { "const": "API_KEY" } }, "required": [ "type", "apiKeyPrefix" ], "type": "object" }, { "properties": { "application": { "type": "string" }, "connectionId": { "$ref": "#/components/schemas/UUID" }, "grantedBy": { "description": "The person who authorised this connection.", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": { "const": "CONNECTION" } }, "required": [ "type", "connectionId", "application", "grantedBy" ], "type": "object" } ] }, { "type": "null" } ] } }, "required": [ "id", "status", "merchant", "reason", "amountMinor", "currency", "requestedAt", "agent" ], "type": "object" }, "PurchaseRequestSummary": { "properties": { "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "currency": { "$ref": "#/components/schemas/Currency" }, "id": { "$ref": "#/components/schemas/UUID" }, "status": { "enum": [ "EVALUATING", "PENDING_APPROVAL", "APPROVED", "REJECTED", "EXPIRED", "CANCELLED" ], "type": "string" } }, "required": [ "id", "status", "amountMinor", "currency" ], "type": "object" }, "RuleEvaluation": { "description": "One rule the Trust Engine considered, including rules that passed and rules that did not apply. An explanation a program cannot inspect only half explains a decision.", "properties": { "currency": { "oneOf": [ { "$ref": "#/components/schemas/Currency" }, { "type": "null" } ] }, "headroomMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorAmount" }, { "type": "null" } ] }, "limitMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorAmount" }, { "type": "null" } ] }, "message": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "observedMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorAmount" }, { "type": "null" } ] }, "outcome": { "type": "string" }, "policyMerchantEntryId": { "oneOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "policyRuleId": { "oneOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "policyVersionId": { "oneOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "reasonCode": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string" }, "rule": { "description": "The rule type as it was written into the policy version, snapshotted at evaluation time.", "type": "string" } }, "required": [ "rule", "outcome", "role" ], "type": "object" }, "SimulatedBudget": { "description": "One budget window: what it currently holds, what this purchase would add, and what the limits say about the sum.", "properties": { "budgetCounterId": { "oneOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "current": { "properties": { "committedMinor": { "$ref": "#/components/schemas/MinorAmount" }, "heldMinor": { "$ref": "#/components/schemas/MinorAmount" }, "openingBalanceMinor": { "$ref": "#/components/schemas/MinorAmount" }, "reservedMinor": { "$ref": "#/components/schemas/MinorAmount" } }, "type": "object" }, "limits": { "items": { "properties": { "effect": { "enum": [ "BLOCK", "REQUIRE_APPROVAL" ], "type": "string" }, "limitMinor": { "$ref": "#/components/schemas/MinorAmount" }, "policyRuleId": { "$ref": "#/components/schemas/UUID" }, "remainingAfterMinor": { "allOf": [ { "$ref": "#/components/schemas/MinorAmount" } ], "description": "Negative reads as \"over by\"." }, "remainingBeforeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "wouldExceed": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "periodEnd": { "$ref": "#/components/schemas/Timestamp" }, "periodKey": { "type": "string" }, "periodKind": { "type": "string" }, "periodStart": { "$ref": "#/components/schemas/Timestamp" }, "policyId": { "$ref": "#/components/schemas/UUID" }, "policyName": { "type": "string" }, "policyVersionId": { "$ref": "#/components/schemas/UUID" }, "simulated": { "properties": { "projectedMinor": { "$ref": "#/components/schemas/MinorAmount" }, "requestedMinor": { "$ref": "#/components/schemas/MinorAmount" } }, "type": "object" }, "wouldExceed": { "type": "boolean" } }, "type": "object" }, "SimulationResponse": { "description": "What a simulation returns. It is not a decision: no purchase request, no decision record, no budget reservation and no audit evidence was created, and no budget was consumed. The identifying fields a real decision carries are absent rather than null, so the two cannot be confused.", "properties": { "agent": { "oneOf": [ { "description": "Present only for a current-policies simulation; null for the two policy-version modes.", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "status": { "enum": [ "ENABLED", "DISABLED", "ARCHIVED" ], "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "budgets": { "items": { "$ref": "#/components/schemas/SimulatedBudget" }, "type": "array" }, "policiesConsidered": { "items": { "properties": { "applicabilityReason": { "type": "string" }, "currencies": { "items": { "$ref": "#/components/schemas/Currency" }, "type": "array" }, "currencyScope": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "policyId": { "$ref": "#/components/schemas/UUID" }, "policyName": { "type": "string" }, "policyStatus": { "enum": [ "ACTIVE", "DISABLED", "ARCHIVED" ], "type": "string" }, "policyVersionId": { "$ref": "#/components/schemas/UUID" }, "scopeType": { "enum": [ "ORGANIZATION", "AGENT" ], "type": "string" }, "versionNumber": { "type": "integer" }, "versionStatus": { "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ], "type": "string" } }, "type": "object" }, "type": "array" }, "policiesExcludedByCurrencyScope": { "description": "Candidates that govern this agent but declared a currency scope excluding this purchase. They changed nothing, and omitting them would make a NO_APPLICABLE_POLICY answer impossible to act on.", "items": { "properties": { "currencies": { "items": { "$ref": "#/components/schemas/Currency" }, "type": "array" }, "currencyScope": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "policyId": { "$ref": "#/components/schemas/UUID" }, "policyName": { "type": "string" }, "policyVersionId": { "$ref": "#/components/schemas/UUID" }, "requestCurrency": { "$ref": "#/components/schemas/Currency" }, "versionNumber": { "type": "integer" } }, "type": "object" }, "type": "array" }, "purchase": { "properties": { "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "currencyExponent": { "type": "integer" }, "merchant": { "type": "string" }, "merchantDomain": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "merchantKey": { "type": "string" } }, "type": "object" }, "ruleEvaluations": { "items": { "allOf": [ { "$ref": "#/components/schemas/RuleEvaluation" }, { "properties": { "policyId": { "oneOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "policyName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" } ] }, "type": "array" }, "simulatedDecision": { "properties": { "explanation": { "type": "string" }, "outcome": { "enum": [ "APPROVED", "REJECTED", "REQUIRES_APPROVAL" ], "type": "string" }, "reasonCodes": { "items": { "enum": [ "WITHIN_POLICY", "MERCHANT_BLOCKED", "MERCHANT_NOT_ALLOW_LISTED", "AMOUNT_EXCEEDS_MAX", "APPROVAL_THRESHOLD_EXCEEDED", "DAILY_LIMIT_EXCEEDED", "MONTHLY_LIMIT_EXCEEDED", "AGENT_DISABLED", "NO_APPLICABLE_POLICY", "CURRENCY_NOT_COVERED", "POLICY_CHANGED_SINCE_ESCALATION" ], "type": "string" }, "type": "array" }, "wouldRequireApproval": { "type": "boolean" } }, "required": [ "outcome", "wouldRequireApproval", "reasonCodes", "explanation" ], "type": "object" }, "simulation": { "properties": { "disclaimer": { "type": "string" }, "engineVersion": { "type": "string" }, "isSimulation": { "const": true, "description": "Always true. The field exists so its absence is a signal." }, "mode": { "type": "string" }, "simulatedAt": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "isSimulation", "mode", "disclaimer", "simulatedAt", "engineVersion" ], "type": "object" } }, "required": [ "simulation", "purchase", "agent", "simulatedDecision", "policiesConsidered", "policiesExcludedByCurrencyScope", "ruleEvaluations", "budgets" ], "type": "object" }, "Timestamp": { "description": "An ISO 8601 instant in UTC, with milliseconds.", "examples": [ "2026-09-08T14:03:21.114Z" ], "format": "date-time", "type": "string" }, "UUID": { "description": "A bare UUID. Identifiers that need to sort by creation time are UUIDv7.", "examples": [ "0199a3f1-8c2e-7b40-9f31-6d2e5a1c0b77" ], "format": "uuid", "type": "string" }, "WebhookDelivery": { "properties": { "attemptCount": { "minimum": 0, "type": "integer" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "deliveredAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "eventId": { "allOf": [ { "$ref": "#/components/schemas/UUID" } ], "description": "The logical event, and your deduplication key. Identical to the Veriticity-Webhook-Id header, and identical at every endpoint subscribed to this event." }, "eventType": { "$ref": "#/components/schemas/DeliverableWebhookEventType" }, "id": { "allOf": [ { "$ref": "#/components/schemas/UUID" } ], "description": "This delivery: one endpoint's attempt stream for one event." }, "lastAttemptAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "lastDurationMs": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "lastErrorClass": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "lastResponseSnippet": { "oneOf": [ { "description": "Up to 512 bytes of your own non-2xx response, returned to you because it is the most useful thing in a failed delivery.", "type": "string" }, { "type": "null" } ] }, "lastStatusCode": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "nextAttemptAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "occurredAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When it happened in the domain, not when it was sent." }, "status": { "type": "string" } }, "required": [ "id", "eventId", "eventType", "occurredAt", "status", "attemptCount", "createdAt" ], "type": "object" }, "WebhookEndpoint": { "properties": { "apiVersion": { "description": "The webhook contract version this endpoint receives. Pinned when the endpoint is created and changed only by PATCH.", "type": "string" }, "consecutiveFailures": { "description": "Veriticity does not disable a failing endpoint, so this is the number that tells you a receiver has been refusing events. Any success resets it.", "minimum": 0, "type": "integer" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "disabledAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/UUID" }, "lastFailureAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "lastSuccessAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "revokedAt": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "status": { "enum": [ "ACTIVE", "DISABLED", "REVOKED" ], "type": "string" }, "subscribedTypes": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "status", "subscribedTypes", "apiVersion", "consecutiveFailures", "createdAt" ], "type": "object" }, "WebhookEnvelope": { "description": "The body of every webhook Veriticity sends. Five fields, fixed. Ignore fields and event types you do not recognise: both may be added at any time without the apiVersion moving.", "properties": { "accountId": { "allOf": [ { "$ref": "#/components/schemas/UUID" } ], "description": "The Veriticity account. Route on this if you serve several." }, "apiVersion": { "examples": [ "2026-09-01" ], "type": "string" }, "createdAt": { "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ], "description": "When it happened in the domain, not when it was sent." }, "data": { "description": "The event payload. Its shape depends on `type`.", "type": "object" }, "id": { "allOf": [ { "$ref": "#/components/schemas/UUID" } ], "description": "The logical event. Stable across retries, identical at every endpoint subscribed to it, and time-ordered because it is a UUIDv7. Deduplicate on this." }, "type": { "$ref": "#/components/schemas/DeliverableWebhookEventType" } }, "required": [ "id", "type", "apiVersion", "createdAt", "accountId", "data" ], "type": "object" }, "WebhookEventType": { "description": "An event type an endpoint may subscribe to. New types may be added at any time; ignore ones you do not recognise.", "enum": [ "purchase.approval_required", "purchase.approved", "purchase.rejected", "purchase.approval_expired", "budget.threshold_reached", "budget.exhausted", "agent.disabled", "agent.archived", "connection.created", "connection.revoked", "security.connection_token_reuse_detected" ], "type": "string", "x-veriticity-event-descriptions": { "agent.archived": "An agent was archived.", "agent.disabled": "An agent was switched off and can no longer buy anything.", "budget.exhausted": "A policy has used its full limit. Purchases under it are being refused.", "budget.threshold_reached": "Spending under a policy has passed 80% of its limit.", "connection.created": "Someone connected an AI assistant to one of your agents.", "connection.revoked": "An AI assistant's access to one of your agents was withdrawn.", "purchase.approval_expired": "Nobody answered in time, so the purchase was refused.", "purchase.approval_required": "A purchase needs a person to approve it before it can go ahead.", "purchase.approved": "A purchase was approved, either by your policies or by a person.", "purchase.rejected": "A purchase was refused, either by your policies or by a person.", "security.connection_token_reuse_detected": "A connected application reused a token it should not have. Its access was withdrawn automatically." } } }, "securitySchemes": { "apiKey": { "description": "A Veriticity API key, as `Authorization: Bearer cmp_live_…`.\n\nKeys come in two kinds and the difference is an authority, not a format:\n\n- **bound to an agent** — submits purchases and reads back its own. It cannot read or change policy.\n- **organization-scoped** — reads the organisation's agents and policies and manages webhooks. It cannot submit purchases, because it names no identity to attribute one to.\n\nEach operation's `x-veriticity-credential` says which it needs. Presenting the wrong kind answers 403 with a code naming the mismatch.", "scheme": "bearer", "type": "http" }, "oauth2": { "description": "An OAuth access token, as `Authorization: Bearer cmp_oat_…`.\n\nA token represents a **connection**: one person's grant letting one application act as one existing agent. OAuth does not create an agent, does not make the application a Veriticity user, and creates no new authority — it is a revocable grant over authority that already existed.\n\nAccess tokens last 60 minutes. Refresh tokens last 90 days and rotate on every use — presenting a consumed one revokes the whole connection.\n\nAuthorization Code with PKCE (`S256`) only. Revocation takes effect on the next call, not at the end of the token's life.", "flows": { "authorizationCode": { "authorizationUrl": "https://app.veriticity.com/oauth/authorize", "refreshUrl": "https://app.veriticity.com/oauth/token", "scopes": { "purchase:check": "Check whether a purchase would be allowed", "purchase:read": "See what happened to purchases it requested", "purchase:request": "Request a purchase" }, "tokenUrl": "https://app.veriticity.com/oauth/token" } }, "type": "oauth2" } } }, "externalDocs": { "description": "Guides, examples and the full developer documentation", "url": "https://docs.veriticity.com" }, "info": { "contact": { "name": "Veriticity developer documentation", "url": "https://docs.veriticity.com" }, "description": "Veriticity is the trust layer between an AI agent and the money it wants to spend. An agent asks whether a purchase is allowed; policies a person wrote decide; and every answer is explained and recorded.\n\nThis document describes the public REST API. Two other surfaces are documented in prose rather than here, because neither is REST:\n\n- **OAuth 2.0** — Authorization Code with PKCE, for connecting an external AI assistant to an existing agent.\n- **MCP** — a Model Context Protocol endpoint at `/mcp`, authenticated by the same OAuth connections.\n\n**Conventions.** Money is always a decimal string of ISO 4217 minor units. Timestamps are ISO 8601 in UTC. Identifiers are bare UUIDs. Unknown request fields are refused rather than ignored. There are currently no rate limits.\n\n**Compatibility.** Fields may be added to responses, and event types may be added, at any time. Ignore what you do not recognise.", "summary": "Spending controls, approvals and an audit trail for AI agents that buy things.", "termsOfService": "https://docs.veriticity.com/terms", "title": "Veriticity API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/v1/agents": { "get": { "description": "The agents in your organisation, with their status.\n\nOrganization-scoped API keys only. An agent-bound credential is refused: a roster of an organisation's other agents is a map of the identities a compromised agent might try to impersonate.\n\nRead-only. Agents are created in the dashboard.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "listAgents", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agents": { "items": { "properties": { "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "status": { "enum": [ "ENABLED", "DISABLED", "ARCHIVED" ], "type": "string" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "id", "name", "status", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" } }, "required": [ "agents" ], "type": "object" } } }, "description": "Every agent in the organisation." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "List this organisation's agents", "tags": [ "Agents" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/policies": { "get": { "description": "Your organisation's spending policies, newest first.\n\nOrganization-scoped API keys only. An agent may not read the policies it is judged against — it learns what it may spend by asking `POST /v1/simulations/current-policies` instead. No OAuth scope reaches this.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "listPolicies", "parameters": [ { "description": "Return only policies in this state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "ACTIVE", "DISABLED", "ARCHIVED" ], "type": "string" } }, { "description": "Free-text match on the policy name. Trimmed, capped at 200 characters, and treated as absent when empty.", "in": "query", "name": "search", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "description": "1-based page number. A page beyond the end returns an empty page rather than a 404, because a filtered set shrinking under a paging UI is normal.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page. Clamped to 100 rather than refused: a caller asking for everything gets the maximum. A malformed value is refused, because it means the client believes something untrue.", "in": "query", "name": "pageSize", "required": false, "schema": { "default": 25, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" }, "policies": { "items": { "$ref": "#/components/schemas/PolicySummary" }, "type": "array" } }, "required": [ "policies", "pagination" ], "type": "object" } } }, "description": "A page of policies, and where it sits in the collection." }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "List spending policies", "tags": [ "Policies" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/policies/{policyId}": { "get": { "description": "One policy with its version history and the agents it governs.\n\nOrganization-scoped API keys only. An agent may not read the policies it is judged against — it learns what it may spend by asking `POST /v1/simulations/current-policies` instead. No OAuth scope reaches this.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "getPolicy", "parameters": [ { "description": "The policy to read.", "in": "path", "name": "policyId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "policy": { "allOf": [ { "$ref": "#/components/schemas/PolicySummary" }, { "properties": { "agentIds": { "items": { "$ref": "#/components/schemas/UUID" }, "type": "array" }, "versions": { "items": { "$ref": "#/components/schemas/PolicyVersionSummary" }, "type": "array" } }, "type": "object" } ] } }, "required": [ "policy" ], "type": "object" } } }, "description": "The policy." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Read one policy", "tags": [ "Policies" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/policies/{policyId}/versions/{versionId}": { "get": { "description": "A policy version in full, including its rules and merchant lists, exactly as the Trust Engine reads it.\n\nOrganization-scoped API keys only. An agent may not read the policies it is judged against — it learns what it may spend by asking `POST /v1/simulations/current-policies` instead. No OAuth scope reaches this.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "getPolicyVersion", "parameters": [ { "description": "The policy the version belongs to.", "in": "path", "name": "policyId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "The version to read.", "in": "path", "name": "versionId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "version": { "$ref": "#/components/schemas/PolicyVersion" } }, "required": [ "version" ], "type": "object" } } }, "description": "The version." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Read one policy version", "tags": [ "Policies" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/policies/{policyId}/versions/{versionId}/validate": { "post": { "description": "Runs activation's own check as a dry run, and **changes nothing**.\n\nAnswers **200 even when the draft is unacceptable** — `valid` carries the verdict and `issues` carries the reasons. A 4xx would mean the question could not be answered, and it was.\n\n`budgetImpact` is empty in the ordinary case. A non-empty one means activating this version would start a limit from a total that already includes spending nobody reserved against.\n\nThis is a `POST` that writes nothing, and it is the only policy operation on `/v1` that is not a plain read.\n\nOrganization-scoped API keys only. An agent may not read the policies it is judged against — it learns what it may spend by asking `POST /v1/simulations/current-policies` instead. No OAuth scope reaches this.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "validatePolicyVersion", "parameters": [ { "description": "The policy the version belongs to.", "in": "path", "name": "policyId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "The version to check.", "in": "path", "name": "versionId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "budgetImpact": { "items": { "properties": { "attributableMinor": { "$ref": "#/components/schemas/MinorAmount" }, "currency": { "$ref": "#/components/schemas/Currency" }, "limits": { "items": { "properties": { "effect": { "type": "string" }, "limitMinor": { "$ref": "#/components/schemas/MinorAmount" }, "remainingMinor": { "$ref": "#/components/schemas/MinorAmount" } }, "type": "object" }, "type": "array" }, "openingBalanceMinor": { "$ref": "#/components/schemas/MinorAmount" }, "periodKey": { "type": "string" }, "periodKind": { "type": "string" }, "reservedMinor": { "$ref": "#/components/schemas/MinorAmount" } }, "type": "object" }, "type": "array" }, "issues": { "items": { "$ref": "#/components/schemas/PolicyIssue" }, "type": "array" }, "valid": { "type": "boolean" }, "version": { "$ref": "#/components/schemas/PolicyVersion" }, "warnings": { "items": { "$ref": "#/components/schemas/PolicyIssue" }, "type": "array" } }, "required": [ "valid", "issues", "warnings", "budgetImpact", "version" ], "type": "object" } } }, "description": "The verdict. `valid` is false when the version could not be activated; this is still a 200." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Check whether a version could be activated", "tags": [ "Policies" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/purchase-requests": { "post": { "description": "Asks the Trust Engine whether this agent may make this purchase, and records the answer.\n\nAll three outcomes — `APPROVED`, `REJECTED` and `REQUIRES_APPROVAL` — are successful calls. **Branch on `decision.outcome`, never on the HTTP status code**: the status describes whether the question could be answered, and a refusal is an answer.\n\n`REQUIRES_APPROVAL` means a person has been asked and the budget is held until `approval.expiresAt`. Poll `GET /v1/purchase-requests/{purchaseRequestId}` for what they decided.\n\nRequires an API key bound to an agent, or an OAuth connection granted `purchase:request`. An organization-scoped key names no identity to attribute a purchase to and is refused.\n\n**Credential:** An API key bound to an agent. OAuth connections need `purchase:request`.", "operationId": "submitPurchaseRequest", "parameters": [ { "description": "Makes a retry safe. The same key with the same body replays the original decision and reserves no further budget, answering 200 rather than 201. The same key with a different body is refused with 409 `idempotency_key_reuse`. This is the only operation that accepts one.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amountMinor": { "description": "A whole number of ISO 4217 minor units. Send it as a string: JSON numbers lose precision above 2^53, and this is money. It is always returned as a string.", "examples": [ "7500" ], "oneOf": [ { "pattern": "^\\d+$", "type": "string" }, { "type": "integer" } ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "description": "Defaults to the organisation's own currency when omitted.", "examples": [ "GBP" ], "oneOf": [ { "pattern": "^[A-Z]{3}$", "type": "string" }, { "type": "null" } ] }, "merchant": { "description": "Who the money would go to, written as a person would name them.", "examples": [ "Acme Cloud" ], "type": "string" }, "merchantDomain": { "description": "Recorded as evidence. Policy is not matched on domains.", "examples": [ "acme-cloud.example.com" ], "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "description": "Anything you want recorded alongside the purchase. No rule reads it.", "oneOf": [ { "type": "object" }, { "type": "null" } ] }, "reason": { "description": "Why the agent wants this purchase. Every purchase must say.", "examples": [ "Renew the build pipeline's compute credits" ], "type": "string" } }, "required": [ "merchant", "reason", "amountMinor" ], "type": "object" } } }, "description": "Unknown fields are refused rather than ignored, with a message saying where authority actually comes from. `organizationId` and `agentId` are never accepted: both are settled by the credential before the body is read.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDecisionResponse" } } }, "description": "An idempotent replay. The stored decision, returned again; no new budget was reserved. `replayed` is true." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDecisionResponse" } } }, "description": "The purchase was evaluated and a decision recorded." }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "malformed_json" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`, `malformed_json`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_bound_to_agent", "insufficient_scope" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_bound_to_agent`, `insufficient_scope`" }, "409": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "idempotency_key_reuse" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`idempotency_key_reuse`" }, "413": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "payload_too_large" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`payload_too_large`" }, "415": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unsupported_media_type" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unsupported_media_type`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] }, { "oauth2": [ "purchase:request" ] } ], "summary": "Submit a purchase for a decision", "tags": [ "Purchases" ], "x-veriticity-credential": "AGENT_BOUND" } }, "/v1/purchase-requests/{purchaseRequestId}": { "get": { "description": "What happened to a purchase, including the decision in force and the approval if one was opened. This is how you find out what a person decided after a `REQUIRES_APPROVAL`.\n\nA purchase is readable by **the credential that submitted it** and by nothing else. Another agent's, another connection's, another tenant's and a malformed id are all the same 404.\n\nReads nothing into the audit trail and re-evaluates nothing.\n\n**Credential:** An API key bound to an agent. OAuth connections need `purchase:read`.", "operationId": "getPurchaseRequest", "parameters": [ { "description": "The purchase request to read.", "in": "path", "name": "purchaseRequestId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchase": { "$ref": "#/components/schemas/PurchaseReadback" } }, "required": [ "purchase" ], "type": "object" } } }, "description": "The purchase, as its submitter may see it." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_bound_to_agent", "insufficient_scope" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_bound_to_agent`, `insufficient_scope`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] }, { "oauth2": [ "purchase:read" ] } ], "summary": "Read back a purchase you submitted", "tags": [ "Purchases" ], "x-veriticity-credential": "AGENT_BOUND" } }, "/v1/simulations/current-policies": { "post": { "description": "Runs the same evaluation `POST /v1/purchase-requests` would run, against the policies currently in force, and **changes nothing**: no purchase request, no decision, no budget reservation, no audit evidence, and no budget consumed.\n\nThis is how an agent finds out what it may spend before committing to asking.\n\nBoth API-key kinds reach it, and they behave differently:\n- an **organization-scoped** key **must** send `agentId`\n- an **agent-bound** key **must not**, and simulates as itself\n- an **OAuth connection** must not, and simulates as its agent\n\n**Credential:** An API key of either kind. OAuth connections need `purchase:check`.", "operationId": "simulateAgainstCurrentPolicies", "requestBody": { "content": { "application/json": { "schema": { "properties": { "agentId": { "description": "Required for an organization-scoped key. Must be omitted by an agent-bound key or an OAuth connection, which simulate as themselves — a credential choosing which agent it asks about would be choosing its own authority.", "oneOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "amountMinor": { "description": "A whole number of ISO 4217 minor units. Send it as a string: JSON numbers lose precision above 2^53, and this is money. It is always returned as a string.", "examples": [ "7500" ], "oneOf": [ { "pattern": "^\\d+$", "type": "string" }, { "type": "integer" } ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "description": "Defaults to the organisation's own currency when omitted.", "examples": [ "GBP" ], "oneOf": [ { "pattern": "^[A-Z]{3}$", "type": "string" }, { "type": "null" } ] }, "merchant": { "description": "Who the money would go to, written as a person would name them.", "examples": [ "Acme Cloud" ], "type": "string" }, "merchantDomain": { "description": "Recorded as evidence. Policy is not matched on domains.", "examples": [ "acme-cloud.example.com" ], "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "description": "Why the agent wants this purchase. Every purchase must say.", "examples": [ "Renew the build pipeline's compute credits" ], "type": "string" } }, "required": [ "merchant", "reason", "amountMinor" ], "type": "object" } } }, "description": "Unknown fields are refused rather than ignored, with a message saying where authority actually comes from. `organizationId` and `agentId` are never accepted: both are settled by the credential before the body is read.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResponse" } } }, "description": "What would have happened. Nothing was changed." }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "malformed_json" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`, `malformed_json`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "insufficient_scope" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `insufficient_scope`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "413": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "payload_too_large" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`payload_too_large`" }, "415": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unsupported_media_type" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unsupported_media_type`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] }, { "oauth2": [ "purchase:check" ] } ], "summary": "Ask what would happen right now", "tags": [ "Simulations" ], "x-veriticity-credential": "ANY" } }, "/v1/simulations/draft-policy": { "post": { "description": "Evaluates a purchase against one `DRAFT` policy version as it is currently written — the question you ask before activating it.\n\nOrganization-scoped API keys only. An agent may not read or simulate the guardrails being drafted for it, and no OAuth scope reaches this.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "simulateDraftPolicy", "requestBody": { "content": { "application/json": { "schema": { "properties": { "amountMinor": { "description": "A whole number of ISO 4217 minor units. Send it as a string: JSON numbers lose precision above 2^53, and this is money. It is always returned as a string.", "examples": [ "7500" ], "oneOf": [ { "pattern": "^\\d+$", "type": "string" }, { "type": "integer" } ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "description": "Defaults to the organisation's own currency when omitted.", "examples": [ "GBP" ], "oneOf": [ { "pattern": "^[A-Z]{3}$", "type": "string" }, { "type": "null" } ] }, "merchant": { "description": "Who the money would go to, written as a person would name them.", "examples": [ "Acme Cloud" ], "type": "string" }, "merchantDomain": { "description": "Recorded as evidence. Policy is not matched on domains.", "examples": [ "acme-cloud.example.com" ], "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "policyVersionId": { "allOf": [ { "$ref": "#/components/schemas/UUID" } ], "description": "The draft version to evaluate. Name the version, not the policy." }, "reason": { "description": "Why the agent wants this purchase. Every purchase must say.", "examples": [ "Renew the build pipeline's compute credits" ], "type": "string" } }, "required": [ "merchant", "reason", "amountMinor", "policyVersionId" ], "type": "object" } } }, "description": "Unknown fields are refused rather than ignored, with a message saying where authority actually comes from. `organizationId` and `agentId` are never accepted: both are settled by the credential before the body is read.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResponse" } } }, "description": "What that draft would have decided." }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "malformed_json" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`, `malformed_json`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "413": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "payload_too_large" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`payload_too_large`" }, "415": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unsupported_media_type" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unsupported_media_type`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Ask what a draft policy version would decide", "tags": [ "Simulations" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/simulations/policy-version": { "post": { "description": "Evaluates a purchase against one `ACTIVE` or `ARCHIVED` policy version exactly as it was frozen — the question you ask about a decision that was already made, or about a version you are thinking of reinstating.\n\nOrganization-scoped API keys only.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "simulatePolicyVersion", "requestBody": { "content": { "application/json": { "schema": { "properties": { "amountMinor": { "description": "A whole number of ISO 4217 minor units. Send it as a string: JSON numbers lose precision above 2^53, and this is money. It is always returned as a string.", "examples": [ "7500" ], "oneOf": [ { "pattern": "^\\d+$", "type": "string" }, { "type": "integer" } ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "description": "Defaults to the organisation's own currency when omitted.", "examples": [ "GBP" ], "oneOf": [ { "pattern": "^[A-Z]{3}$", "type": "string" }, { "type": "null" } ] }, "merchant": { "description": "Who the money would go to, written as a person would name them.", "examples": [ "Acme Cloud" ], "type": "string" }, "merchantDomain": { "description": "Recorded as evidence. Policy is not matched on domains.", "examples": [ "acme-cloud.example.com" ], "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "policyVersionId": { "allOf": [ { "$ref": "#/components/schemas/UUID" } ], "description": "The active or archived version to evaluate." }, "reason": { "description": "Why the agent wants this purchase. Every purchase must say.", "examples": [ "Renew the build pipeline's compute credits" ], "type": "string" } }, "required": [ "merchant", "reason", "amountMinor", "policyVersionId" ], "type": "object" } } }, "description": "Unknown fields are refused rather than ignored, with a message saying where authority actually comes from. `organizationId` and `agentId` are never accepted: both are settled by the credential before the body is read.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResponse" } } }, "description": "What that version would have decided." }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "malformed_json" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`, `malformed_json`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "413": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "payload_too_large" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`payload_too_large`" }, "415": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unsupported_media_type" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unsupported_media_type`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Ask what a specific policy version would decide", "tags": [ "Simulations" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/webhooks": { "get": { "description": "Every webhook endpoint on the account, including revoked ones — the delivery history against a revoked endpoint is the answer to \"where were our events going in March\".\n\nNever carries a signing secret.\n\nOrganization-scoped API keys only. An agent-bound credential must not be able to decide where the whole account's events go, and **no OAuth scope reaches this at all** — admitting a connection would let an AI assistant point your event stream at a URL of its own choosing.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "listWebhookEndpoints", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "The account's endpoints." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" }, "post": { "description": "Registers a URL to receive events, and returns the signing secret.\n\n**The secret is shown once.** Veriticity cannot show it again — store it before you close the response. If you lose it, rotate.\n\nThe URL must be HTTPS on port 443, must be a hostname rather than an IP literal, must carry no userinfo, and must resolve to a publicly routable address. This is checked now and again before every delivery. A URL that fails answers `webhook_url_not_permitted`.\n\nNew endpoints are created on the current webhook API version.\n\nOrganization-scoped API keys only. An agent-bound credential must not be able to decide where the whole account's events go, and **no OAuth scope reaches this at all** — admitting a connection would let an AI assistant point your event stream at a URL of its own choosing.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "createWebhookEndpoint", "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "For your own reference. Never sent anywhere.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "subscribedTypes": { "description": "Choose at least one event to receive.", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "minItems": 1, "type": "array" }, "url": { "examples": [ "https://hooks.example.com/veriticity" ], "format": "uri", "type": "string" } }, "required": [ "url", "subscribedTypes" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedWebhookEndpoint" } } }, "description": "Created. **Carries the signing secret, once.**" }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "malformed_json", "webhook_url_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`, `malformed_json`, `webhook_url_not_permitted`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "409": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "webhook_limit_reached" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`webhook_limit_reached`" }, "413": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "payload_too_large" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`payload_too_large`" }, "415": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unsupported_media_type" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unsupported_media_type`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" }, "503": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "webhook_not_configured" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`webhook_not_configured`" } }, "security": [ { "apiKey": [] } ], "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/webhooks/{webhookId}": { "delete": { "description": "Stops delivery permanently and destroys the endpoint's signing secrets. **Revocation is terminal** — it cannot be undone, and a revoked endpoint cannot be re-enabled. Create a new one instead.\n\nReturns the endpoint in its revoked state rather than `204`: the row is not gone, it still appears in listings, and its delivery history survives.\n\nOrganization-scoped API keys only. An agent-bound credential must not be able to decide where the whole account's events go, and **no OAuth scope reaches this at all** — admitting a connection would let an AI assistant point your event stream at a URL of its own choosing.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "revokeWebhookEndpoint", "parameters": [ { "description": "The endpoint to revoke.", "in": "path", "name": "webhookId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "The endpoint, now revoked." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "409": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "webhook_endpoint_revoked" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`webhook_endpoint_revoked`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Revoke a webhook endpoint", "tags": [ "Webhooks" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" }, "get": { "description": "One endpoint, including its operational health. `consecutiveFailures` is the number that tells you a receiver has been refusing events since Tuesday; any success resets it.\n\nNever carries a signing secret.\n\nOrganization-scoped API keys only. An agent-bound credential must not be able to decide where the whole account's events go, and **no OAuth scope reaches this at all** — admitting a connection would let an AI assistant point your event stream at a URL of its own choosing.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "getWebhookEndpoint", "parameters": [ { "description": "The endpoint to read.", "in": "path", "name": "webhookId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "The endpoint." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Read a webhook endpoint", "tags": [ "Webhooks" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" }, "patch": { "description": "Changes the URL, description, subscriptions, status or API version. Send at least one field.\n\nOmitting `description` leaves it alone; sending `null` clears it.\n\n`status` accepts `ACTIVE` and `DISABLED` only. Revoking destroys key material and cannot be undone, so it is its own verb: `DELETE /v1/webhooks/{webhookId}`.\n\nThe secret is never changed here — use rotate-secret.\n\nOrganization-scoped API keys only. An agent-bound credential must not be able to decide where the whole account's events go, and **no OAuth scope reaches this at all** — admitting a connection would let an AI assistant point your event stream at a URL of its own choosing.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "updateWebhookEndpoint", "parameters": [ { "description": "The endpoint to update.", "in": "path", "name": "webhookId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "minProperties": 1, "properties": { "apiVersion": { "type": "string" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "ACTIVE", "DISABLED" ], "type": "string" }, "subscribedTypes": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "minItems": 1, "type": "array" }, "url": { "format": "uri", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "The updated endpoint." }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "malformed_json", "webhook_url_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`, `malformed_json`, `webhook_url_not_permitted`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "409": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "webhook_endpoint_revoked" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`webhook_endpoint_revoked`" }, "413": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "payload_too_large" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`payload_too_large`" }, "415": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unsupported_media_type" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unsupported_media_type`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/webhooks/{webhookId}/deliveries": { "get": { "description": "Recent delivery attempts, newest first — what was sent, what your server answered, and when the next attempt is due.\n\n`hasMore` rather than a total: what a debugging session wants is \"is there anything older\", and counting a table that only grows costs a scan to answer a question nobody asks.\n\nThis is a third pagination model, distinct from the page/pageSize used by `GET /v1/policies`.\n\nOrganization-scoped API keys only. An agent-bound credential must not be able to decide where the whole account's events go, and **no OAuth scope reaches this at all** — admitting a connection would let an AI assistant point your event stream at a URL of its own choosing.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "listWebhookDeliveries", "parameters": [ { "description": "The endpoint whose deliveries these are.", "in": "path", "name": "webhookId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "How many attempts to return.", "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "hasMore": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" } }, "required": [ "items", "hasMore" ], "type": "object" } } }, "description": "A page of delivery attempts." }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" } }, "security": [ { "apiKey": [] } ], "summary": "Read an endpoint's delivery history", "tags": [ "Webhooks" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/webhooks/{webhookId}/rotate-secret": { "post": { "description": "Issues a new signing secret and returns it once.\n\nBy default the old secret keeps signing for **24 hours** alongside the new one, so every delivery in that window carries two signatures and a receiver verifying with either succeeds. That is what lets you deploy the new secret without coordinating a cutover.\n\nSend `{\"retireImmediately\": true}` to kill the old secret at once, which is what a leak calls for.\n\nThe body is optional: an absent body means the defaults. This is the only operation on the API that does not require a JSON body when it takes one.\n\nOrganization-scoped API keys only. An agent-bound credential must not be able to decide where the whole account's events go, and **no OAuth scope reaches this at all** — admitting a connection would let an AI assistant point your event stream at a URL of its own choosing.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "rotateWebhookSecret", "parameters": [ { "description": "The endpoint to rotate.", "in": "path", "name": "webhookId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "retireImmediately": { "default": false, "description": "Retire the old secret now instead of after 24 hours. Deliveries signed with it stop verifying immediately.", "type": "boolean" } }, "type": "object" } } }, "description": "Optional. An absent body means a 24-hour overlap.", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedWebhookEndpoint" } } }, "description": "Rotated. **Carries the new signing secret, once.**" }, "400": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "malformed_json" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`invalid_request`, `malformed_json`" }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "409": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "webhook_endpoint_revoked" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`webhook_endpoint_revoked`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" }, "503": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "webhook_not_configured" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`webhook_not_configured`" } }, "security": [ { "apiKey": [] } ], "summary": "Rotate an endpoint's signing secret", "tags": [ "Webhooks" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } }, "/v1/webhooks/{webhookId}/test": { "post": { "description": "Queues a real `webhook.test` event through the real pipeline: signed with your real secret, recorded as a real delivery, retried on the real schedule. There is no verification handshake — this is better, because it proves the thing you actually care about on every request rather than once.\n\nAnswers **202**, not 200: the event is queued rather than delivered. Use the returned ids to find it in the delivery history.\n\nDelivered regardless of what the endpoint subscribes to.\n\nOrganization-scoped API keys only. An agent-bound credential must not be able to decide where the whole account's events go, and **no OAuth scope reaches this at all** — admitting a connection would let an AI assistant point your event stream at a URL of its own choosing.\n\n**Credential:** An organization-scoped API key. No OAuth scope reaches this operation.", "operationId": "sendTestWebhookEvent", "parameters": [ { "description": "The endpoint to send a test to.", "in": "path", "name": "webhookId", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "deliveryId": { "$ref": "#/components/schemas/UUID" }, "eventId": { "$ref": "#/components/schemas/UUID" }, "status": { "const": "queued" } }, "required": [ "eventId", "deliveryId", "status" ], "type": "object" } } }, "description": "Queued. Look in the delivery history for what happened." }, "401": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthorized", "invalid_api_key", "api_key_revoked", "api_key_expired", "wrong_environment", "invalid_token" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`, `invalid_token`", "headers": { "WWW-Authenticate": { "description": "Always `Bearer realm=\"compass\"`.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "connection_unauthorized", "organization_suspended", "api_key_not_organization_scoped", "oauth_not_permitted" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`connection_unauthorized`, `organization_suspended`, `api_key_not_organization_scoped`, `oauth_not_permitted`" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`not_found`" }, "409": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "webhook_endpoint_revoked" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`webhook_endpoint_revoked`" }, "500": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`internal_error`" }, "503": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "webhook_not_configured" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "`webhook_not_configured`" } }, "security": [ { "apiKey": [] } ], "summary": "Send a test event", "tags": [ "Webhooks" ], "x-veriticity-credential": "ORGANIZATION_SCOPED" } } }, "security": [ { "apiKey": [] } ], "servers": [ { "description": "Production", "url": "https://app.veriticity.com" } ], "tags": [ { "description": "Submit a purchase for a decision, and find out what happened to it.", "name": "Purchases" }, { "description": "Ask what would happen, without anything happening. Simulations create no records and consume no budget.", "name": "Simulations" }, { "description": "Read the spending rules in force. Policies are authored by a person in the dashboard, never by an API credential.", "name": "Policies" }, { "description": "The identities that spend.", "name": "Agents" }, { "description": "Receive events when purchases are decided, budgets move, or connections change.", "name": "Webhooks" } ], "webhooks": { "agent.archived": { "post": { "description": "An agent was archived.\n\nVeriticity POSTs this to every active endpoint subscribed to `agent.archived`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onAgentArchived", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "An agent was archived.", "tags": [ "Webhooks" ] } }, "agent.disabled": { "post": { "description": "An agent was switched off and can no longer buy anything.\n\nVeriticity POSTs this to every active endpoint subscribed to `agent.disabled`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onAgentDisabled", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "An agent was switched off and can no longer buy anything.", "tags": [ "Webhooks" ] } }, "budget.exhausted": { "post": { "description": "A policy has used its full limit. Purchases under it are being refused.\n\nVeriticity POSTs this to every active endpoint subscribed to `budget.exhausted`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onBudgetExhausted", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "A policy has used its full limit. Purchases under it are being refused.", "tags": [ "Webhooks" ] } }, "budget.threshold_reached": { "post": { "description": "Spending under a policy has passed 80% of its limit.\n\nVeriticity POSTs this to every active endpoint subscribed to `budget.threshold_reached`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onBudgetThresholdReached", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "Spending under a policy has passed 80% of its limit.", "tags": [ "Webhooks" ] } }, "connection.created": { "post": { "description": "Someone connected an AI assistant to one of your agents.\n\nVeriticity POSTs this to every active endpoint subscribed to `connection.created`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onConnectionCreated", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "Someone connected an AI assistant to one of your agents.", "tags": [ "Webhooks" ] } }, "connection.revoked": { "post": { "description": "An AI assistant's access to one of your agents was withdrawn.\n\nVeriticity POSTs this to every active endpoint subscribed to `connection.revoked`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onConnectionRevoked", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "An AI assistant's access to one of your agents was withdrawn.", "tags": [ "Webhooks" ] } }, "purchase.approval_expired": { "post": { "description": "Nobody answered in time, so the purchase was refused.\n\nVeriticity POSTs this to every active endpoint subscribed to `purchase.approval_expired`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onPurchaseApprovalExpired", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "Nobody answered in time, so the purchase was refused.", "tags": [ "Webhooks" ] } }, "purchase.approval_required": { "post": { "description": "A purchase needs a person to approve it before it can go ahead.\n\nVeriticity POSTs this to every active endpoint subscribed to `purchase.approval_required`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onPurchaseApprovalRequired", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "A purchase needs a person to approve it before it can go ahead.", "tags": [ "Webhooks" ] } }, "purchase.approved": { "post": { "description": "A purchase was approved, either by your policies or by a person.\n\nVeriticity POSTs this to every active endpoint subscribed to `purchase.approved`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onPurchaseApproved", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "A purchase was approved, either by your policies or by a person.", "tags": [ "Webhooks" ] } }, "purchase.rejected": { "post": { "description": "A purchase was refused, either by your policies or by a person.\n\nVeriticity POSTs this to every active endpoint subscribed to `purchase.rejected`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onPurchaseRejected", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "A purchase was refused, either by your policies or by a person.", "tags": [ "Webhooks" ] } }, "security.connection_token_reuse_detected": { "post": { "description": "A connected application reused a token it should not have. Its access was withdrawn automatically.\n\nVeriticity POSTs this to every active endpoint subscribed to `security.connection_token_reuse_detected`. Answer 2xx to acknowledge. Verify the signature over the **raw request body bytes** before parsing.\n\nDelivery is at-least-once and duplicates are possible: deduplicate on `Veriticity-Webhook-Id`.", "operationId": "onSecurityConnectionTokenReuseDetected", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is a success and no retry follows." }, "4XX": { "description": "Permanent failure, except 408 and 429 which are retried. The event is dropped for this endpoint." }, "5XX": { "description": "Retried, up to 7 attempts over roughly 24 hours." } }, "summary": "A connected application reused a token it should not have. Its access was withdrawn automatically.", "tags": [ "Webhooks" ] } }, "webhook.test": { "post": { "description": "Sent by `POST /v1/webhooks/{webhookId}/test`. A real event through the real pipeline, signed with the real secret — it is not an application event and carries no invented purchase data, because a test carrying fake numbers would teach you to build against numbers that were never real.\n\nDelivered regardless of what the endpoint subscribes to.", "operationId": "onWebhookTest", "parameters": [ { "description": "The logical event. Stable across retries and identical at every endpoint subscribed to this event. **Deduplicate on this.**", "in": "header", "name": "Veriticity-Webhook-Id", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "This attempt's delivery. Changes between retries.", "in": "header", "name": "Veriticity-Webhook-Delivery", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "description": "Unix seconds. Part of the signed material. Reject anything more than 5 minutes from your own clock, in either direction.", "in": "header", "name": "Veriticity-Webhook-Timestamp", "required": true, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "`v1=`, comma-separated when more than one secret is active. During the 24 hours after a rotation there are two, and verifying with either is a success. The signed input is `v1:{timestamp}:{raw body}`, HMAC-SHA256 under the endpoint's signing secret.", "in": "header", "name": "Veriticity-Webhook-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledged." } }, "summary": "A test event you asked for.", "tags": [ "Webhooks" ] } } }, "x-veriticity-error-codes": { "api_key_expired": 401, "api_key_not_bound_to_agent": 403, "api_key_not_organization_scoped": 403, "api_key_not_permitted": 403, "api_key_revoked": 401, "budget_reconciliation_inconsistent": 409, "connection_unauthorized": 403, "draft_invalid": 422, "idempotency_key_reuse": 409, "insufficient_scope": 403, "internal_error": 500, "invalid_api_key": 401, "invalid_request": 400, "invalid_token": 401, "malformed_json": 400, "not_found": 404, "oauth_not_permitted": 403, "organization_suspended": 403, "payload_too_large": 413, "policy_lifecycle_conflict": 409, "policy_name_taken": 409, "unauthorized": 401, "unsupported_media_type": 415, "webhook_endpoint_revoked": 409, "webhook_limit_reached": 409, "webhook_not_configured": 503, "webhook_url_not_permitted": 400, "wrong_environment": 401 }, "x-veriticity-webhook-api-version": "2026-09-01" }