{ "openapi": "3.1.0", "info": { "title": "Watchdog API (preview)", "version": "1.0.0", "description": "Development preview for agreements, price items, document relationships, canonical invoices, alerts and alert topics, claims and attached alerts, shared entity activity and comments, Document uploads, invoice imports, explicit invoice-agreement matching, and workflow runs. This contract is under development and is not served by api.watchdog.no. Request bodies are limited to 2 MiB (2,097,152 bytes), including all JSON fields and line data, except POST /v1/support/contact which permits 32 MiB for base64 attachments. File bytes are uploaded directly to storage. The existing public REST service retains its separate contract." }, "servers": [{ "url": "http://localhost:3500", "description": "Local development Worker" }], "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "description": "Personal API key. Send X-Organization-Id. The required cumulative level is listed in x-watchdog-permission." }, "ClerkSessionBearer": { "type": "http", "scheme": "bearer", "description": "Clerk session with an active organization." } }, "schemas": { "TeamFilterDefinition": { "type": "object", "properties": { "schema_version": { "type": "number", "enum": [1] }, "root": { "$ref": "#/components/schemas/TeamFilterRoot" } }, "required": ["schema_version", "root"], "additionalProperties": false, "description": "Version 1 saved predicate. At most 20 conditions and 3 group levels. Groups preserve explicit AND/OR structure. Exact operators accept a scalar or nonempty list of at most 100 values; prefer is/is_not for scalars and is_any_of/is_none_of for lists. Independent conditions over related records may match different records. Amount is invoice total including VAT, without currency conversion. See the Teams guide for field mapping, missing values, and UTC relative dates." }, "TeamFilterRoot": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["and", "or"] }, "children": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TeamReferenceCondition" }, { "$ref": "#/components/schemas/TeamExactTextCondition" }, { "$ref": "#/components/schemas/TeamContainsCondition" }, { "$ref": "#/components/schemas/TeamNumberCondition" }, { "$ref": "#/components/schemas/TeamDateCondition" }, { "$ref": "#/components/schemas/TeamRelativeDateCondition" }, { "$ref": "#/components/schemas/TeamFilterGroupLevel2" } ] }, "minItems": 1, "maxItems": 20 } }, "required": ["combinator", "children"], "additionalProperties": false }, "TeamReferenceCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": ["supplier.id", "recipient.id", "agreement.id", "agreement.tag"] }, "op": { "type": "string", "enum": ["is", "is_not", "is_any_of", "is_none_of"] }, "value": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } ] } }, "required": ["field", "op", "value"], "additionalProperties": false }, "TeamExactTextCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "supplier.country", "invoice.currency", "invoice.reference", "invoice.delivery_address" ] }, "op": { "type": "string", "enum": ["is", "is_not", "is_any_of", "is_none_of"] }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100 } ] } }, "required": ["field", "op", "value"], "additionalProperties": false }, "TeamContainsCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "supplier.country", "invoice.currency", "invoice.reference", "invoice.delivery_address" ] }, "op": { "type": "string", "enum": ["contains", "not_contains"] }, "value": { "type": "string", "minLength": 1 } }, "required": ["field", "op", "value"], "additionalProperties": false }, "TeamNumberCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": ["invoice.amount"] }, "op": { "type": "string", "enum": ["eq", "gt", "gte", "lt", "lte"] }, "value": { "anyOf": [{ "type": "number" }, { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }] } }, "required": ["field", "op", "value"], "additionalProperties": false }, "TeamDateCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": ["agreement.expiration_date", "invoice.issued_date"] }, "op": { "type": "string", "enum": ["on", "before", "on_or_before", "after", "on_or_after"] }, "value": { "type": "string", "format": "date" } }, "required": ["field", "op", "value"], "additionalProperties": false }, "TeamRelativeDateCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": ["agreement.expiration_date", "invoice.issued_date"] }, "op": { "type": "string", "enum": ["within"] }, "value": { "type": "string", "enum": [ "last_30_days", "last_90_days", "last_365_days", "expiring_30_days", "expiring_60_days", "expiring_90_days" ] } }, "required": ["field", "op", "value"], "additionalProperties": false }, "TeamFilterGroupLevel2": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["and", "or"] }, "children": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TeamReferenceCondition" }, { "$ref": "#/components/schemas/TeamExactTextCondition" }, { "$ref": "#/components/schemas/TeamContainsCondition" }, { "$ref": "#/components/schemas/TeamNumberCondition" }, { "$ref": "#/components/schemas/TeamDateCondition" }, { "$ref": "#/components/schemas/TeamRelativeDateCondition" }, { "$ref": "#/components/schemas/TeamFilterGroupLevel3" } ] }, "minItems": 1, "maxItems": 20 } }, "required": ["combinator", "children"], "additionalProperties": false }, "TeamFilterGroupLevel3": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["and", "or"] }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/TeamFilterCondition" }, "minItems": 1, "maxItems": 20 } }, "required": ["combinator", "children"], "additionalProperties": false }, "TeamFilterCondition": { "anyOf": [ { "$ref": "#/components/schemas/TeamReferenceCondition" }, { "$ref": "#/components/schemas/TeamExactTextCondition" }, { "$ref": "#/components/schemas/TeamContainsCondition" }, { "$ref": "#/components/schemas/TeamNumberCondition" }, { "$ref": "#/components/schemas/TeamDateCondition" }, { "$ref": "#/components/schemas/TeamRelativeDateCondition" } ] }, "NotificationPreferencesDocument": { "type": "object", "properties": { "preferences": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationPreferences" } } }, "required": ["preferences"] }, "NotificationPreferences": { "oneOf": [ { "type": "object", "properties": { "owner": { "type": "string", "enum": ["personal"] }, "scope": { "type": "string", "enum": ["mine", "organization"] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "personal": { "type": "boolean" }, "filter": { "$ref": "#/components/schemas/StoredSubscriptionFilter" }, "references": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": ["string", "null"] }, "missing": { "type": "boolean" }, "type": { "type": "string", "enum": ["supplier", "recipient", "agreement", "agreement_tag"] } }, "required": ["id", "name", "missing", "type"] } } }, "required": ["id", "name", "personal", "filter", "references"] } }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannelPreferences" } } }, "required": ["owner", "scope", "sources", "channels"] }, { "type": "object", "properties": { "owner": { "type": "string", "enum": ["organization"] }, "scope": { "type": "string", "enum": ["organization"] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "personal": { "type": "boolean" }, "filter": { "$ref": "#/components/schemas/StoredSubscriptionFilter" }, "references": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": ["string", "null"] }, "missing": { "type": "boolean" }, "type": { "type": "string", "enum": ["supplier", "recipient", "agreement", "agreement_tag"] } }, "required": ["id", "name", "missing", "type"] } } }, "required": ["id", "name", "personal", "filter", "references"] }, "maxItems": 0 }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannelPreferences" } } }, "required": ["owner", "scope", "sources", "channels"] } ] }, "StoredSubscriptionFilter": { "description": "Saved subscription filter JSON, shared by teams and personal notification sources. Teams return it verbatim, including null or invalid legacy definitions; notification sources include only usable filters. Use TeamFilterDefinition to author a replacement." }, "NotificationChannelPreferences": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The notification channel used by these preferences." }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string", "enum": ["new_alert", "agreement_expiring"] } }, "readiness": { "type": "string", "enum": ["ready", "disabled", "no_events", "no_sources", "invalid_destination"] } }, "required": ["id", "enabled", "events", "readiness"] }, "Error_validation_error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["validation_error"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "Error_invalid_token": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["invalid_token"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "forbidden", "token_disabled", "organization_required", "insufficient_role", "mfa_required" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "Error_rate_limit_exceeded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["rate_limit_exceeded"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "Error_internal_error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "Error_service_unavailable": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["service_unavailable"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "Error_not_found": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["not_found"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "Error_conflict": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["conflict"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "UpdateNotificationPreferences": { "oneOf": [ { "type": "object", "properties": { "owner": { "type": "string", "enum": ["personal"] }, "scope": { "type": "string", "enum": ["mine", "organization"] }, "channels": { "type": "array", "items": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string", "enum": ["new_alert", "agreement_expiring"] }, "maxItems": 2, "uniqueItems": true }, "id": { "type": "string", "format": "uuid" } }, "required": ["id"], "additionalProperties": false, "anyOf": [{ "required": ["enabled"] }, { "required": ["events"] }] }, "minItems": 1, "description": "Updates to existing channels owned by the selected owner. Channel IDs must be unique." } }, "required": ["owner"], "additionalProperties": false, "anyOf": [{ "required": ["scope"] }, { "required": ["channels"] }] }, { "type": "object", "properties": { "owner": { "type": "string", "enum": ["organization"] }, "channels": { "type": "array", "items": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string", "enum": ["new_alert", "agreement_expiring"] }, "maxItems": 2, "uniqueItems": true }, "id": { "type": "string", "format": "uuid" } }, "required": ["id"], "additionalProperties": false, "anyOf": [{ "required": ["enabled"] }, { "required": ["events"] }] }, "minItems": 1, "description": "Updates to existing channels owned by the selected owner. Channel IDs must be unique." } }, "required": ["owner", "channels"], "additionalProperties": false } ] }, "NotificationChannel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": ["email", "slack"] }, "owner": { "type": "string", "enum": ["personal", "organization"] }, "destination": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } } }, "required": ["type", "recipients"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["slack"] }, "channel_id": { "type": "string" }, "channel_name": { "type": "string" } }, "required": ["type", "channel_id", "channel_name"] }, { "type": "null" } ] }, "delivery_summary": { "type": "object", "properties": { "days": { "type": "number", "enum": [30] }, "events": { "type": "integer" }, "suppliers": { "type": "integer" }, "deadlines": { "type": "integer" } }, "required": ["days", "events", "suppliers", "deadlines"] } }, "required": ["id", "type", "owner", "destination", "delivery_summary"] }, "CreateNotificationChannel": { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] } }, "required": ["type"], "additionalProperties": false }, "Overview": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "organization_currency": { "type": "string" }, "periods": { "type": "object", "properties": { "coverage": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": ["start", "end"] }, "recent": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": ["start", "end"] } }, "required": ["coverage", "recent"] }, "agreement_count": { "type": "integer", "minimum": 0 }, "has_invoices": { "type": "boolean" }, "invoice_spend": { "$ref": "#/components/schemas/OverviewMonetaryMetric" }, "claims": { "type": "object", "properties": { "awaiting": { "$ref": "#/components/schemas/OverviewMonetaryMetric" }, "refunded": { "$ref": "#/components/schemas/OverviewMonetaryMetric" } }, "required": ["awaiting", "refunded"] }, "alerts": { "type": "object", "properties": { "pending": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "value": { "$ref": "#/components/schemas/OverviewMonetaryMetric" } }, "required": ["count", "value"] } }, "required": ["pending"] }, "next_steps": { "type": "array", "items": { "$ref": "#/components/schemas/OverviewNextStep" }, "description": "Applicable actions in priority order, each with its own display counts and target." } }, "required": [ "as_of", "timezone", "organization_currency", "periods", "agreement_count", "has_invoices", "invoice_spend", "claims", "alerts", "next_steps" ] }, "OverviewMonetaryMetric": { "type": "object", "properties": { "total": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": ["string", "null"] }, "amount": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": ["string", "null"] }, "amount": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Amounts for periods.recent." } }, "required": ["total", "recent"] }, "OverviewNextStep": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["add_invoices", "add_agreement", "upload_more_invoices"] } }, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["review_alerts"] }, "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } }, "required": ["type", "count"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["run_missing_checks"] }, "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 } }, "required": ["type", "count"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["finish_agreement", "cancel_renewing_agreement", "renew_agreement"] }, "count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 }, "agreement_id": { "type": ["string", "null"], "format": "uuid", "description": "The target when count is one; otherwise null." } }, "required": ["type", "count", "agreement_id"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["add_supplier_agreements"] }, "supplier_count": { "type": "integer", "minimum": 0, "exclusiveMinimum": 0 }, "invoice_count": { "type": "integer", "minimum": 0 }, "coverage_ratio": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": ["type", "supplier_count", "invoice_count", "coverage_ratio"] } ] }, "AgreementSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "active", "archived"] }, "effective_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "expiration_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "suppliers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_number": { "type": ["string", "null"] } }, "required": ["id", "name", "organization_number"] }, "example": [], "description": "Complete supplier selection. An empty array matches no invoices." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_number": { "type": ["string", "null"] } }, "required": ["id", "name", "organization_number"] }, "example": [], "description": "Complete recipient selection. An empty array means any recipient." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "description": "Complete assigned tags, ordered by ID. Empty means no tags.", "example": [] }, "version": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "alert_summary": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "claimed": { "type": "integer", "minimum": 0 }, "dismissed": { "type": "integer", "minimum": 0 }, "credited": { "type": "integer", "minimum": 0 } }, "required": ["pending", "claimed", "dismissed", "credited"] }, "pending_topic_count": { "type": "integer", "minimum": 0, "description": "Topics with at least one pending alert. Pending uncategorized alerts count as one topic." }, "organization_currency": { "type": "object", "properties": { "currency_code": { "type": "string", "description": "The organization's reporting currency from its settings." }, "impact_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "missing_amount_count": { "type": "integer" }, "impact_by_status": { "type": "object", "properties": { "pending": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "claimed": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "credited": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "dismissed": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["pending", "claimed", "credited", "dismissed"] } }, "required": [ "currency_code", "impact_amount", "missing_amount_count", "impact_by_status" ], "description": "Impact converted with the rate stored on each alert. Alerts without a converted impact contribute zero and are counted in missing_amount_count." } }, "required": ["counts", "pending_topic_count", "organization_currency"], "description": "All retained alerts of this agreement, as GET /v1/alerts/metrics?agreement_ids={id} reports them. Team filters select agreements; they do not narrow this summary." }, "relationships": { "type": "object", "properties": { "price_item_count": { "type": "integer", "minimum": 0 }, "document_count": { "type": "integer", "minimum": 0 }, "invoice_match_count": { "type": "integer", "minimum": 0, "description": "Number of completed, non-deleted invoices currently matched to this agreement. Equals total_count from /v1/invoices/metrics?agreement_ids={id} without additional filters." } }, "required": ["price_item_count", "document_count", "invoice_match_count"] } }, "required": [ "id", "title", "status", "effective_date", "expiration_date", "suppliers", "recipients", "tags", "version", "created_at", "updated_at", "alert_summary", "relationships" ] }, "InvoiceSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "extraction_confirmed": { "type": "boolean", "readOnly": true, "description": "Explicit human review acknowledgment; independent of extraction confidence and financial validity." }, "extraction_confirmed_at": { "type": ["string", "null"], "format": "date-time", "readOnly": true }, "extraction_confirmed_by_user_id": { "type": ["string", "null"], "readOnly": true }, "invoice_number": { "type": ["string", "null"] }, "title": { "type": ["string", "null"] }, "category": { "type": "string", "enum": ["invoice", "credit_note", "self_billed_invoice"] }, "issued_date": { "type": ["string", "null"], "format": "date" }, "due_date": { "type": ["string", "null"], "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": ["string", "null"], "format": "date-time" }, "currency_code": { "type": ["string", "null"] }, "total_amount_excluding_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "total_amount_including_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "financially_valid": { "type": "boolean", "readOnly": true, "description": "Deterministic arithmetic within a tolerance of 1 currency unit. Does not imply extraction accuracy, compliance, or human approval." }, "financial_errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_financial_inputs", "line_calculation_mismatch", "invoice_total_mismatch", "invoice_subtotal_mismatch", "category_amount_mismatch" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "readOnly": true }, "alert_summary": { "$ref": "#/components/schemas/InvoiceAlertSummary" }, "supplier_name": { "type": ["string", "null"], "description": "Current canonical supplier name. Used by supplier ordering." }, "recipient_name": { "type": ["string", "null"], "description": "Current canonical recipient name. Used by recipient ordering." }, "review_recommended": { "type": "boolean", "readOnly": true, "description": "Review is recommended for low or medium unconfirmed extraction confidence, an unmatched credit note, or financial invalidity. Uses the same predicate as the review_recommended filter." }, "extraction_confidence": { "type": "string", "enum": ["high", "mid", "low", "unknown"], "description": "Lowest original header/line confidence from the creating import, when both stages have reliable evidence. Structured, XML and unavailable historical evidence are unknown; manual confirmation does not change this value." }, "relationships": { "type": "object", "properties": { "linked_credit_note_count": { "type": "integer", "minimum": 0, "description": "Recorded credit notes linked to an ordinary or self-billed invoice." }, "matched_invoice_count": { "type": "integer", "minimum": 0, "description": "Recorded invoices matched from a credit note." } }, "required": ["linked_credit_note_count", "matched_invoice_count"], "description": "Recorded org-owned links including soft-deleted counterparts. A match does not establish financial resolution." }, "supplier_id": { "type": ["string", "null"], "format": "uuid", "description": "Current canonical supplier ID." }, "recipient_id": { "type": ["string", "null"], "format": "uuid", "description": "Current canonical recipient ID." }, "supplier_snapshot": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "organization_number": { "type": ["string", "null"] } }, "required": ["name", "organization_number"], "description": "Supplier details captured on the invoice." }, "recipient_snapshot": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "organization_number": { "type": ["string", "null"] } }, "required": ["name", "organization_number"], "description": "Recipient details captured on the invoice." } }, "required": [ "id", "extraction_confirmed", "extraction_confirmed_at", "extraction_confirmed_by_user_id", "invoice_number", "title", "category", "issued_date", "due_date", "created_at", "updated_at", "deleted_at", "currency_code", "total_amount_excluding_vat", "total_amount_including_vat", "financially_valid", "financial_errors", "alert_summary", "supplier_name", "recipient_name", "review_recommended", "extraction_confidence", "relationships", "supplier_id", "recipient_id", "supplier_snapshot", "recipient_snapshot" ] }, "InvoiceAlertSummary": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice", "selected_agreements"], "description": "invoice evaluates overall coverage and all retained alerts; selected_agreements evaluates only selected current matches." }, "agreement_ids": { "type": ["array", "null"], "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Null means overall invoice coverage; otherwise only these selected, currently matched agreements." } }, "required": ["type", "agreement_ids"] }, "checks": { "type": "object", "properties": { "status": { "type": "string", "enum": ["not_checkable", "checking", "not_checked", "completed", "incomplete"] }, "completed": { "type": "integer", "minimum": 0, "description": "Currently matched agreements with a completed check, including outdated or unknown check inputs reported in reasons." }, "total": { "type": "integer", "minimum": 0, "description": "Currently matched, nondeleted agreements." }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "credit_note", "credit_note_matched", "no_agreements", "missing", "failed", "cancelled", "outdated", "invoice_changed", "unknown" ] }, "description": "outdated means a completed check read an earlier agreement version or invoice; invoice_changed accompanies it when the invoice is what moved. credit_note_matched means the invoice has a linked completed, nondeleted credit note; active partial or shared credits also block checks." } }, "required": ["status", "completed", "total", "reasons"] }, "counts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "claimed": { "type": "integer", "minimum": 0 }, "dismissed": { "type": "integer", "minimum": 0 }, "credited": { "type": "integer", "minimum": 0 } }, "required": ["pending", "claimed", "dismissed", "credited"], "description": "All retained alerts, including dismissed and outdated alerts." }, "is_fully_credited": { "type": "boolean", "description": "A completed, nondeleted credit note uniquely targets this invoice and offsets its total including VAT within 1 currency unit, in the same currency." }, "has_credit_note_match": { "type": "boolean", "description": "A recorded match, not verification that findings were financially resolved." } }, "required": ["scope", "checks", "counts", "is_fully_credited", "has_credit_note_match"] }, "Profile": { "type": "object", "properties": { "first_name": { "type": ["string", "null"] }, "last_name": { "type": ["string", "null"] }, "email_addresses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "format": "email" }, "verified": { "type": "boolean" }, "primary": { "type": "boolean" } }, "required": ["id", "email", "verified", "primary"] } }, "has_password": { "type": "boolean" }, "can_delete_account": { "type": "boolean" } }, "required": [ "first_name", "last_name", "email_addresses", "has_password", "can_delete_account" ] }, "PersonalApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "level": { "type": "string", "enum": ["read", "write", "admin"] }, "access": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["all"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["selected"] }, "organization_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "minItems": 1, "maxItems": 100 } }, "required": ["mode", "organization_ids"], "additionalProperties": false } ] }, "status": { "type": "string", "enum": ["active", "suspended", "revoked"] }, "original_organization_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": ["string", "null"] } }, "required": ["id", "name"] } }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": ["string", "null"], "format": "date-time" }, "disabled_at": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "id", "name", "level", "access", "status", "original_organization_id", "organizations", "created_at", "revoked_at", "disabled_at" ] }, "CreatedPersonalApiKey": { "allOf": [ { "$ref": "#/components/schemas/PersonalApiKey" }, { "type": "object", "properties": { "token": { "type": "string" } }, "required": ["token"] } ] }, "Identity": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "type": { "type": "string", "enum": ["api_key", "clerk_session"] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "user_id": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["type", "id", "user_id"] } }, "required": ["principal"] }, "UsagePeriod": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "unit": { "type": "string", "enum": ["invoice"] }, "consumed": { "type": "integer" }, "allowance": { "type": ["integer", "null"] }, "overage": { "type": ["integer", "null"] }, "policy_revision_id": { "type": ["string", "null"], "format": "uuid" }, "capacity": { "type": ["object", "null"], "properties": { "eligible": { "type": "boolean" }, "remaining": { "type": ["integer", "null"] }, "reason": { "type": "string", "enum": ["available", "limit_reached"] }, "reserved": { "type": "integer" }, "as_of": { "type": "string", "format": "date-time" } }, "required": ["eligible", "remaining", "reason", "reserved", "as_of"] } }, "required": [ "period", "period_start", "period_end", "unit", "consumed", "allowance", "overage", "policy_revision_id", "capacity" ] }, "UsagePolicy": { "type": "object", "properties": { "current_month": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "billing_timezone": { "type": "string" }, "billing_started": { "type": "boolean" }, "policy": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["none"] } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["configured"] }, "included_quantity": { "type": "integer", "minimum": 0 }, "overage": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["disallowed"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["capped"] }, "quantity": { "type": "integer", "minimum": 0, "maximum": 10000000, "exclusiveMinimum": 0 } }, "required": ["mode", "quantity"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["uncapped"] } }, "required": ["mode"], "additionalProperties": false } ] } }, "required": ["kind", "included_quantity", "overage"] } ] }, "governing_revision": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "effective_month": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "created_at": { "type": "string", "format": "date-time" } }, "required": ["id", "effective_month", "created_at"] }, "upcoming_policies": { "type": "array", "items": { "type": "object", "properties": { "effective_month": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "policy": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["none"] } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["configured"] }, "included_quantity": { "type": "integer", "minimum": 0 }, "overage": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["disallowed"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["capped"] }, "quantity": { "type": "integer", "minimum": 0, "maximum": 10000000, "exclusiveMinimum": 0 } }, "required": ["mode", "quantity"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["uncapped"] } }, "required": ["mode"], "additionalProperties": false } ] } }, "required": ["kind", "included_quantity", "overage"] } ] } }, "required": ["effective_month", "policy"] } } }, "required": [ "current_month", "billing_timezone", "billing_started", "policy", "governing_revision", "upcoming_policies" ] }, "UsagePolicyRevision": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "effective_month": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "created_at": { "type": "string", "format": "date-time" }, "superseded": { "type": "boolean" }, "actor": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["watchdog_staff"] } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["organization_member"] }, "email": { "type": "string" } }, "required": ["kind", "email"] } ] }, "operation": { "type": "string", "enum": ["set", "remove", "schedule_cancelled"] }, "policy": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["none"] } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["configured"] }, "included_quantity": { "type": "integer", "minimum": 0 }, "overage": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["disallowed"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["capped"] }, "quantity": { "type": "integer", "minimum": 0, "maximum": 10000000, "exclusiveMinimum": 0 } }, "required": ["mode", "quantity"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["uncapped"] } }, "required": ["mode"], "additionalProperties": false } ] } }, "required": ["kind", "included_quantity", "overage"] }, { "type": "null" } ] }, "cancelled_revision_id": { "type": ["string", "null"], "format": "uuid" } }, "required": [ "id", "effective_month", "created_at", "superseded", "actor", "operation", "policy", "cancelled_revision_id" ] }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string" }, "slug": { "type": ["string", "null"] }, "logo_url": { "type": ["string", "null"] }, "settings": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "timezone": { "type": "string" }, "language": { "type": "string", "enum": ["en", "nb"] }, "require_mfa": { "type": "boolean" }, "agreement_defaults": { "type": "object", "properties": { "alerts": { "type": "object", "properties": { "flag_undercharges": { "type": "boolean" }, "flag_uncovered_items": { "type": "boolean" } }, "required": ["flag_undercharges", "flag_uncovered_items"], "additionalProperties": false } }, "required": ["alerts"] }, "conversion_workflow": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "completed_with_errors", "failed", "cancelled" ] } }, "required": ["id", "status"] } }, "required": [ "currency", "timezone", "language", "require_mfa", "agreement_defaults", "conversion_workflow" ] }, "access": { "type": "object", "properties": { "role": { "type": "string", "enum": ["admin", "member", "unsupported"] }, "configured_level": { "type": "string", "enum": ["read", "write", "admin"] }, "effective_level": { "type": "string", "enum": ["read", "write", "admin"] } }, "required": ["role", "configured_level", "effective_level"] }, "members_count": { "type": "integer", "minimum": 0 }, "member_limit": { "type": ["integer", "null"], "exclusiveMinimum": 0, "description": "Synchronized Clerk membership capacity for display. Null means unlimited; omitted until synchronized. Clerk enforces the current limit when changing membership." }, "capabilities": { "type": "object", "properties": { "can_delete": { "type": "boolean", "description": "The caller has effective Admin access to request organization deletion. Provider availability and current membership are checked when deleting." }, "can_manage_members": { "type": "boolean", "description": "The caller has effective Admin access to manage memberships and invitations." }, "supported_roles": { "type": "array", "items": { "type": "string", "enum": ["admin", "member"] } } }, "required": ["can_delete", "can_manage_members", "supported_roles"] } }, "required": [ "id", "name", "slug", "logo_url", "settings", "access", "members_count", "capabilities" ] }, "OrganizationMember": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "organization_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "first_name": { "type": ["string", "null"] }, "last_name": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] }, "role": { "type": "string", "enum": ["admin", "member", "unsupported"] }, "joined_at": { "type": "string", "format": "date-time" } }, "required": [ "user_id", "organization_id", "first_name", "last_name", "email", "role", "joined_at" ] }, "OrganizationInvitation": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["admin", "member", "unsupported"] }, "status": { "type": ["string", "null"], "enum": ["pending", "accepted", "revoked", "expired", null] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": ["id", "email", "role", "status", "created_at", "expires_at"] }, "Error_no_eligible_agreements_check_in_progress_conflict": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["no_eligible_agreements", "check_in_progress", "conflict"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "AgreementsCheckAccepted": { "type": "object", "properties": { "workflow_run_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "One agreement check per agreement." }, "has_more": { "type": "boolean", "description": "More unchecked invoices remain than one request admits. Repeat after these finish." } }, "required": ["workflow_run_ids", "has_more"] }, "AgreementCheckAccepted": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" }, "invoice_count": { "type": "integer", "exclusiveMinimum": 0, "description": "Invoices this check evaluates." }, "has_more": { "type": "boolean", "description": "More unchecked invoices remain than one request admits. Repeat after these finish." } }, "required": ["workflow_run_id", "invoice_count", "has_more"] }, "Error_agreement_not_checkable_nothing_to_check_conflict": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["agreement_not_checkable", "nothing_to_check", "conflict"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "TopicRecheckAccepted": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" }, "invoice_count": { "type": "integer", "exclusiveMinimum": 0, "description": "Invoices this recheck evaluates." }, "skipped_count": { "type": "integer", "minimum": 0, "description": "The topic's other invoices, left as they are: a claim holds the pair, the pair is being checked, or the invoice cannot be checked against the agreement." } }, "required": ["workflow_run_id", "invoice_count", "skipped_count"] }, "CheckReset": { "type": "object", "properties": { "deleted_alert_count": { "type": "integer", "minimum": 0 }, "kept_alert_count": { "type": "integer", "minimum": 0, "description": "Alerts kept because a claim holds their invoice and agreement pair." }, "cancelled_check_count": { "type": "integer", "minimum": 0, "description": "Unfinished checks that were cancelled." } }, "required": ["deleted_alert_count", "kept_alert_count", "cancelled_check_count"] }, "ComplianceCheck": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" }, "summary": { "type": "string" }, "finding_count": { "type": "integer", "minimum": 0 }, "completeness": { "type": "string", "enum": ["complete", "incomplete"], "description": "incomplete: the investigation reached its budget but established findings." }, "assessed": { "type": "object", "properties": { "agreement_version": { "type": "integer" }, "invoice_fingerprint": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Identity and checksum of every invoice and agreement document that was read." } }, "required": ["agreement_version", "invoice_fingerprint", "sources"], "description": "Inputs this evaluation read. Never rewritten." }, "freshness": { "type": "string", "enum": ["current", "outdated"], "description": "Derived on read by comparing assessed inputs with the live invoice and agreement." }, "completed_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "invoice_id", "agreement_id", "workflow_run_item_id", "summary", "finding_count", "completeness", "assessed", "freshness", "completed_at" ] }, "ComplianceCheckFinding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable identity of the finding. Never reused by another check." }, "alert_id": { "type": "string", "format": "uuid", "description": "The alert this finding became when the check completed. A later check may have replaced that alert." }, "title": { "type": ["string", "null"] }, "explanation": { "type": ["string", "null"] }, "correction_type": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "currency": { "type": "string" }, "impact_amount": { "type": ["string", "null"] }, "confidence": { "type": "object", "properties": { "level": { "type": ["string", "null"] }, "reason": { "type": ["string", "null"] } }, "required": ["level", "reason"] }, "questions": { "type": "array", "items": { "type": "string" } }, "invoice_line": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": ["integer", "null"] }, "product_code": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "unit": { "type": ["string", "null"] } }, "required": ["id", "line_number", "product_code", "description", "unit"] }, "invoiced": { "type": "object", "properties": { "base_price": { "type": ["string", "null"] }, "net_price": { "type": ["string", "null"] }, "quantity": { "type": ["string", "null"] }, "discount": { "type": ["string", "null"] }, "surcharge": { "type": ["string", "null"] }, "total": { "type": ["string", "null"] } }, "required": ["base_price", "net_price", "quantity", "discount", "surcharge", "total"] }, "expected": { "type": "object", "properties": { "base_price": { "type": ["string", "null"] }, "quantity": { "type": ["string", "null"] }, "discount": { "type": ["string", "null"] }, "surcharge": { "type": ["string", "null"] }, "adjustment_uplift": { "type": ["string", "null"] }, "net_price": { "type": ["string", "null"] }, "total": { "type": ["string", "null"] }, "price_explanation": { "type": ["string", "null"] }, "adjustment_explanation": { "type": ["string", "null"] }, "product_code": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "unit": { "type": ["string", "null"] } }, "required": [ "base_price", "quantity", "discount", "surcharge", "adjustment_uplift", "net_price", "total", "price_explanation", "adjustment_explanation", "product_code", "description", "unit" ] }, "price_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "item_no": { "type": "integer" }, "product_code": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "unit": { "type": ["string", "null"] }, "currency": { "type": ["string", "null"] }, "unit_price": { "type": ["string", "null"] }, "discount_rate": { "type": ["string", "null"] }, "price_type": { "type": ["string", "null"] }, "rate_fraction": { "type": ["string", "null"] }, "rate_basis": { "type": ["string", "null"] }, "surcharge_rate": { "type": ["string", "null"] }, "applies_to": { "type": ["string", "null"] }, "calculation_rules": { "type": ["string", "null"] }, "valid_from": { "type": ["string", "null"] }, "valid_until": { "type": ["string", "null"] } }, "required": [ "id", "item_no", "product_code", "description", "unit", "currency", "unit_price", "discount_rate", "price_type", "rate_fraction", "rate_basis", "surcharge_rate", "applies_to", "calculation_rules", "valid_from", "valid_until" ] } }, "citations": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Cited evidence as assessed, including exact excerpts and locations." }, "position": { "type": "integer", "minimum": 0, "description": "Order of the finding within its check." } }, "required": [ "id", "alert_id", "title", "explanation", "correction_type", "currency", "impact_amount", "confidence", "questions", "invoice_line", "invoiced", "expected", "price_items", "citations", "position" ] }, "ComplianceCheckTranscript": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["assistant", "tool"] }, "tool_name": { "type": ["string", "null"], "description": "The tool that produced a tool entry." }, "text": { "type": "string" } }, "required": ["kind", "tool_name", "text"] } } }, "required": ["entries"] }, "TimelineEntry": { "oneOf": [ { "$ref": "#/components/schemas/Activity" }, { "$ref": "#/components/schemas/Comment" } ], "discriminator": { "propertyName": "type", "mapping": { "activity": "#/components/schemas/Activity", "comment": "#/components/schemas/Comment" } } }, "Activity": { "type": "object", "properties": { "type": { "type": "string", "enum": ["activity"] }, "id": { "type": "string", "format": "uuid" }, "entity_type": { "type": "string", "enum": [ "agreement", "invoice", "alert", "claim", "topic", "invoice_import", "document" ] }, "entity_id": { "type": "string", "format": "uuid" }, "occurred_at": { "type": "string", "format": "date-time" }, "action": { "type": "string", "description": "Extensible domain action identifier. Consumers must accept unknown actions." }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": ["user", "system", "integration"] }, "user_id": { "type": ["string", "null"] }, "source": { "type": ["string", "null"] }, "label": { "type": ["string", "null"] } }, "required": ["type", "user_id", "source", "label"] }, "detail": { "$ref": "#/components/schemas/ActivityDetailV1" }, "entity_version": { "type": ["integer", "null"] } }, "required": [ "type", "id", "entity_type", "entity_id", "occurred_at", "action", "actor", "detail", "entity_version" ] }, "ActivityDetailV1": { "type": ["object", "null"], "properties": { "schemaVersion": { "type": "number", "enum": [1] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "from": { "$ref": "#/components/schemas/ActivityValue" }, "to": { "$ref": "#/components/schemas/ActivityValue" } }, "required": ["field", "from", "to"], "additionalProperties": { "$ref": "#/components/schemas/ActivityValue" } } }, "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ActivityValue" } }, "operation": { "type": "string" }, "summary": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ActivityValue" } } }, "required": ["schemaVersion"], "additionalProperties": false }, "ActivityValue": { "type": ["string", "number", "boolean", "null", "array", "object"], "items": { "$ref": "#/components/schemas/ActivityValue" }, "additionalProperties": { "$ref": "#/components/schemas/ActivityValue" } }, "Comment": { "type": "object", "properties": { "type": { "type": "string", "enum": ["comment"] }, "id": { "type": "string", "format": "uuid" }, "entity_type": { "type": "string", "enum": ["invoice", "agreement", "alert", "claim"] }, "entity_id": { "type": "string", "format": "uuid" }, "parent_comment_id": { "type": ["string", "null"], "format": "uuid" }, "body": { "type": "string" }, "author": { "type": "object", "properties": { "user_id": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] } }, "required": ["user_id", "name"] }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "reply_count": { "type": "integer", "minimum": 0 } }, "required": [ "type", "id", "entity_type", "entity_id", "parent_comment_id", "body", "author", "occurred_at", "created_at", "updated_at", "reply_count" ] }, "ClaimRefund": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "amount": { "type": "string" }, "currency_code": { "type": "string" }, "comment": { "type": ["string", "null"] }, "credit_note_id": { "type": ["string", "null"], "format": "uuid" }, "created_by_user_id": { "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "amount", "currency_code", "comment", "credit_note_id", "created_by_user_id", "created_at", "updated_at" ] }, "Error_precondition_failed": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["precondition_failed"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "ClaimCreditNote": { "type": "object", "properties": { "credit_note": { "$ref": "#/components/schemas/InvoiceSummary" }, "direct_attachment": { "type": ["object", "null"], "properties": { "attached_at": { "type": "string", "format": "date-time" }, "refund_created_by_attachment": { "type": "boolean" }, "refund": { "allOf": [ { "$ref": "#/components/schemas/ClaimRefund" }, { "type": ["object", "null"] } ] } }, "required": ["attached_at", "refund_created_by_attachment", "refund"] }, "matched_invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] } }, "required": ["id", "title"] }, "description": "Claim invoices this credit note is matched to, ordered by invoice number (missing numbers last) and ID; title is the invoice number." } }, "required": ["credit_note", "direct_attachment", "matched_invoices"] }, "Error_precondition_required": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["precondition_required"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "ClaimInvoiceDocuments": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] } }, "required": ["id", "title"], "description": "The invoice; title is its invoice number." }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDocument" }, "description": "Primary document first, then by position." } }, "required": ["invoice", "documents"] }, "InvoiceDocument": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "role": { "type": "string", "enum": ["primary", "attachment"] }, "position": { "type": ["integer", "null"] } }, "required": ["document", "role", "position"] }, "Document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "mime_type": { "type": ["string", "null"] }, "file_size": { "type": ["integer", "null"] }, "page_count": { "type": ["integer", "null"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": ["string", "null"], "format": "date-time" }, "version": { "type": ["integer", "null"] }, "previous_version_id": { "type": ["string", "null"], "format": "uuid" } }, "required": [ "id", "file_name", "mime_type", "file_size", "page_count", "created_at", "updated_at", "version", "previous_version_id" ] }, "Claim": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agreement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] } }, "required": ["id", "title"] }, "suppliers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": ["id", "name"] } }, "title": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "creator": { "type": ["object", "null"], "properties": { "user_id": { "type": ["string", "null"] }, "label": { "type": ["string", "null"] } }, "required": ["user_id", "label"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "refund_summary": { "type": "object", "properties": { "refund_count": { "type": "integer" }, "amount_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] } } }, "required": ["refund_count", "amount_by_currency"] }, "summary": { "type": "object", "properties": { "total": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "All currently attached alerts. The pending, claimed, credited, and dismissed populations partition it." }, "pending": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "Attached alerts with status pending; still under review and not yet counted as pursued." }, "claimed": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "Attached alerts with status claimed; amounts being pursued." }, "credited": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "Attached alerts with status credited; amounts are alert impact, not recorded credits or refunds." }, "dismissed": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "Attached alerts with status dismissed; amounts excluded from pursuit." } }, "required": ["total", "pending", "claimed", "credited", "dismissed"] } }, "required": [ "id", "agreement", "suppliers", "title", "status", "creator", "created_at", "updated_at", "refund_summary", "summary" ] }, "ClaimMetrics": { "type": "object", "properties": { "total_count": { "type": "integer" }, "counts": { "type": "object", "properties": { "pending": { "type": "integer" }, "in_progress": { "type": "integer" }, "completed": { "type": "integer" }, "cancelled": { "type": "integer" } }, "required": ["pending", "in_progress", "completed", "cancelled"] }, "refund_summary": { "type": "object", "properties": { "refund_count": { "type": "integer" }, "amount_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] } } }, "required": ["refund_count", "amount_by_currency"] }, "summary": { "type": "object", "properties": { "total": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "All currently attached alerts. The pending, claimed, credited, and dismissed populations partition it." }, "pending": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "Attached alerts with status pending; still under review and not yet counted as pursued." }, "claimed": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "Attached alerts with status claimed; amounts being pursued." }, "credited": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "Attached alerts with status credited; amounts are alert impact, not recorded credits or refunds." }, "dismissed": { "type": "object", "properties": { "alert_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices in this population. An invoice with multiple alert statuses counts in each applicable group, but only once in total." }, "topic_count": { "type": "integer", "description": "Distinct topics represented by alerts in this population. Alerts without a topic do not contribute. A topic with multiple statuses counts in each applicable group, but only once in total." }, "impact_by_currency": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "amount"] }, "description": "Exact amounts in original currencies. Null alert impacts contribute zero." } }, "required": ["alert_count", "invoice_count", "topic_count", "impact_by_currency"], "description": "Attached alerts with status dismissed; amounts excluded from pursuit." } }, "required": ["total", "pending", "claimed", "credited", "dismissed"] } }, "required": ["total_count", "counts", "refund_summary", "summary"] }, "AlertSelectionResult": { "type": "object", "properties": { "changed_count": { "type": "integer", "description": "Alerts the command changed. Alerts already in the requested state are not counted." }, "skipped_count": { "type": "integer", "description": "Filter selections only: matching alerts that may not be changed and were left alone. Always 0 for alert_ids." } }, "required": ["changed_count", "skipped_count"] }, "AlertSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] }, "explanation": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "correction_type": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "confidence": { "type": "object", "properties": { "level": { "type": ["string", "null"], "enum": ["high", "mid", "low", null] }, "reason": { "type": ["string", "null"] } }, "required": ["level", "reason"] }, "impact_amount": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "currency_code": { "type": "string" }, "organization_currency": { "type": "object", "properties": { "currency_code": { "type": "string", "description": "The organization's reporting currency from its settings." }, "impact_amount": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["currency_code", "impact_amount"], "description": "The impact converted with the rate stored on the alert." }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "invoice": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": ["string", "null"] }, "title": { "type": ["string", "null"], "description": "The invoice's own title; its number is invoice_number." }, "category": { "type": "string", "enum": ["invoice", "credit_note", "self_billed_invoice"] }, "issued_date": { "type": ["string", "null"], "format": "date" }, "due_date": { "type": ["string", "null"], "format": "date" }, "currency_code": { "type": ["string", "null"] }, "total_amount_including_vat": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": [ "id", "invoice_number", "title", "category", "issued_date", "due_date", "currency_code", "total_amount_including_vat" ] }, "invoice_item": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": "integer" }, "product_code": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "unit": { "type": ["string", "null"] } }, "required": ["id", "line_number", "product_code", "description", "unit"], "readOnly": true, "description": "Current linked invoice line details, not a snapshot at alert creation. Null when no accessible line is linked." }, "agreement": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "active", "archived"] }, "version": { "type": "integer", "description": "The current agreement version." } }, "required": ["id", "title", "status", "version"] }, "supplier": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] } }, "required": ["id", "title"] }, "recipient": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] } }, "required": ["id", "title"] }, "topic": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] }, "is_locked": { "type": "boolean" } }, "required": ["id", "title", "is_locked"] }, "claim": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] } }, "required": ["id", "title", "status"], "description": "The claim this alert is currently attached to, if any." }, "provenance": { "type": "object", "properties": { "agreement_version": { "type": ["integer", "null"], "description": "The agreement version assessed; compare with agreement.version." }, "invoice_fingerprint": { "type": ["string", "null"] }, "retained_check": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" } }, "required": ["id"], "description": "The immutable ComplianceCheck that produced this alert. Null for alerts created before retained checks existed; history is never reconstructed." } }, "required": ["agreement_version", "invoice_fingerprint", "retained_check"] }, "correction_relationships": { "type": "array", "items": { "type": "object", "properties": { "replacement_alert_id": { "type": "string", "format": "uuid" }, "replaced_alert_id": { "type": "string", "format": "uuid" } }, "required": ["replacement_alert_id", "replaced_alert_id"] }, "maxItems": 100, "description": "Links between an added-item alert and the line alerts it replaces. Alerts connected by these links form one replacement set." }, "correction_relationships_truncated": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "explanation", "status", "correction_type", "confidence", "impact_amount", "currency_code", "organization_currency", "freshness", "invoice", "invoice_item", "agreement", "supplier", "recipient", "topic", "claim", "provenance", "correction_relationships", "correction_relationships_truncated", "created_at", "updated_at" ] }, "AlertMetrics": { "type": "object", "properties": { "total_count": { "type": "integer" }, "invoice_count": { "type": "integer", "description": "Distinct invoices among the matching alerts." }, "counts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "claimed": { "type": "integer", "minimum": 0 }, "dismissed": { "type": "integer", "minimum": 0 }, "credited": { "type": "integer", "minimum": 0 } }, "required": ["pending", "claimed", "dismissed", "credited"] }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": "string" }, "alert_count": { "type": "integer" }, "missing_amount_count": { "type": "integer" }, "impact_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Sum of known alert impacts. Null impacts contribute zero; missing_amount_count records how many were omitted." } }, "required": ["currency_code", "alert_count", "missing_amount_count", "impact_amount"] } }, "organization_currency": { "type": "object", "properties": { "currency_code": { "type": "string", "description": "The organization's reporting currency from its settings." }, "impact_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "missing_amount_count": { "type": "integer" }, "impact_by_status": { "type": "object", "properties": { "pending": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "claimed": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "credited": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "dismissed": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["pending", "claimed", "credited", "dismissed"] } }, "required": [ "currency_code", "impact_amount", "missing_amount_count", "impact_by_status" ], "description": "Impact converted with the rate stored on each alert. Alerts without a converted impact contribute zero and are counted in missing_amount_count." } }, "required": [ "total_count", "invoice_count", "counts", "currencies", "organization_currency" ] }, "AlertGroup": { "allOf": [ { "$ref": "#/components/schemas/AlertMetrics" }, { "type": "object", "properties": { "group_by": { "type": "string", "enum": ["agreement", "invoice", "topic", "claim", "status", "freshness"] }, "key": { "type": ["string", "null"], "description": "The group's value in its dimension filter: an agreement, invoice, topic or claim ID, a status, or a freshness. Null means no topic or no claim; filter with null to select it." }, "resource": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] } }, "required": ["id", "title"], "description": "The agreement, invoice (titled by invoice number), topic or claim of the group. Null for status and freshness groups and for alerts without a topic or claim." } }, "required": ["group_by", "key", "resource"] } ] }, "Alert": { "allOf": [ { "$ref": "#/components/schemas/AlertSummary" }, { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "string" } }, "price_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Agreement price items the finding relies on. Read them with GET /v1/agreements/{id}/price-items?ids=." }, "expected": { "type": "object", "properties": { "base_price": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "quantity": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "adjustment_uplift": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "net_price": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$", "readOnly": true, "description": "Calculated from expected pricing inputs." }, "total": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$", "readOnly": true, "description": "Calculated from expected net price and quantity." }, "price_explanation": { "type": ["string", "null"] }, "adjustment_explanation": { "type": ["string", "null"] }, "product_code": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "unit": { "type": ["string", "null"] } }, "required": [ "base_price", "quantity", "discount", "surcharge", "adjustment_uplift", "net_price", "total", "price_explanation", "adjustment_explanation", "product_code", "description", "unit" ] }, "invoiced": { "type": "object", "properties": { "base_price": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "net_price": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "quantity": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "total": { "type": ["string", "null"], "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": [ "base_price", "net_price", "quantity", "discount", "surcharge", "total" ], "readOnly": true, "description": "Pricing values captured when the alert was created." }, "evidence": { "type": "object", "properties": { "citations": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["document"] }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": ["string", "null"], "maxLength": 10000 }, "page": { "type": ["string", "null"], "maxLength": 10000 }, "section_title": { "type": ["string", "null"], "maxLength": 10000 }, "context_before": { "type": ["string", "null"], "maxLength": 10000 }, "context_after": { "type": ["string", "null"], "maxLength": 10000 }, "original_quote": { "type": ["string", "null"], "maxLength": 10000 } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "document_id", "document_name", "page", "section_title", "context_before", "context_after", "original_quote" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["web"] }, "url": { "type": ["string", "null"], "maxLength": 10000 }, "cited_at": { "type": ["string", "null"], "maxLength": 10000 } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "url", "cited_at" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["agreement_items"] }, "item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agreement_item_refs": { "type": "array", "items": { "type": "string", "maxLength": 10000 } } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "item_ids", "agreement_item_refs" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["user_context"] } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type" ] }, { "type": "object", "properties": { "source_ref": { "type": ["integer", "null"], "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "source_type": { "type": ["string", "null"] }, "page": { "type": ["string", "null"], "maxLength": 10000 }, "section_title": { "type": ["string", "null"], "maxLength": 10000 }, "context_before": { "type": ["string", "null"], "maxLength": 10000 }, "context_after": { "type": ["string", "null"], "maxLength": 10000 }, "original_quote": { "type": ["string", "null"], "maxLength": 10000 }, "available": { "type": "boolean", "enum": [false] }, "reason": { "type": "string", "enum": ["source_unavailable"] } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "source_type", "page", "section_title", "context_before", "context_after", "original_quote", "available", "reason" ] } ] } }, "truncated": { "type": "boolean", "description": "Excerpts are cut at 10,000 characters. Stored evidence is unchanged." } }, "required": ["citations", "truncated"] } }, "required": ["questions", "price_item_ids", "expected", "invoiced", "evidence"] } ] }, "AlertTopic": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agreement": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": ["string", "null"] } }, "required": ["id", "title"] }, "title": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "is_locked": { "type": "boolean" }, "counts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "claimed": { "type": "integer", "minimum": 0 }, "dismissed": { "type": "integer", "minimum": 0 }, "credited": { "type": "integer", "minimum": 0 } }, "required": ["pending", "claimed", "dismissed", "credited"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agreement", "title", "description", "is_locked", "counts", "created_at", "updated_at" ] }, "AlertTopicDetail": { "allOf": [ { "$ref": "#/components/schemas/AlertTopic" }, { "type": "object", "properties": { "key_questions": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "object", "properties": { "citations": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["document"] }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": ["string", "null"], "maxLength": 10000 }, "page": { "type": ["string", "null"], "maxLength": 10000 }, "section_title": { "type": ["string", "null"], "maxLength": 10000 }, "context_before": { "type": ["string", "null"], "maxLength": 10000 }, "context_after": { "type": ["string", "null"], "maxLength": 10000 }, "original_quote": { "type": ["string", "null"], "maxLength": 10000 } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "document_id", "document_name", "page", "section_title", "context_before", "context_after", "original_quote" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["web"] }, "url": { "type": ["string", "null"], "maxLength": 10000 }, "cited_at": { "type": ["string", "null"], "maxLength": 10000 } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "url", "cited_at" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["agreement_items"] }, "item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agreement_item_refs": { "type": "array", "items": { "type": "string", "maxLength": 10000 } } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "item_ids", "agreement_item_refs" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["user_context"] } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type" ] }, { "type": "object", "properties": { "source_ref": { "type": ["integer", "null"], "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "source_type": { "type": ["string", "null"] }, "page": { "type": ["string", "null"], "maxLength": 10000 }, "section_title": { "type": ["string", "null"], "maxLength": 10000 }, "context_before": { "type": ["string", "null"], "maxLength": 10000 }, "context_after": { "type": ["string", "null"], "maxLength": 10000 }, "original_quote": { "type": ["string", "null"], "maxLength": 10000 }, "available": { "type": "boolean", "enum": [false] }, "reason": { "type": "string", "enum": ["source_unavailable"] } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "source_type", "page", "section_title", "context_before", "context_after", "original_quote", "available", "reason" ] } ] } }, "truncated": { "type": "boolean", "description": "Excerpts are cut at 10,000 characters. Stored evidence is unchanged." } }, "required": ["citations", "truncated"] } }, "required": ["key_questions", "evidence"] } ] }, "AlertTopicProposal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": ["merge", "split"] }, "topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The topics the proposal replaces." }, "instructions": { "type": ["string", "null"] }, "topics": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "description": "Stable within this proposal, e.g. NT1." }, "title": { "type": "string" }, "description": { "type": "string", "description": "Markdown. Inline citations such as [1] refer to this topic’s citations." }, "key_questions": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["document"] }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": ["string", "null"], "maxLength": 10000 }, "page": { "type": ["string", "null"], "maxLength": 10000 }, "section_title": { "type": ["string", "null"], "maxLength": 10000 }, "context_before": { "type": ["string", "null"], "maxLength": 10000 }, "context_after": { "type": ["string", "null"], "maxLength": 10000 }, "original_quote": { "type": ["string", "null"], "maxLength": 10000 } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "document_id", "document_name", "page", "section_title", "context_before", "context_after", "original_quote" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["web"] }, "url": { "type": ["string", "null"], "maxLength": 10000 }, "cited_at": { "type": ["string", "null"], "maxLength": 10000 } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "url", "cited_at" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["agreement_items"] }, "item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agreement_item_refs": { "type": "array", "items": { "type": "string", "maxLength": 10000 } } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type", "item_ids", "agreement_item_refs" ] }, { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "available": { "type": "boolean", "enum": [true] }, "source_type": { "type": "string", "enum": ["user_context"] } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "available", "source_type" ] }, { "type": "object", "properties": { "source_ref": { "type": ["integer", "null"], "exclusiveMinimum": 0 }, "citation_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": ["string", "null"], "maxLength": 10000 }, "quote": { "type": ["string", "null"], "maxLength": 10000 }, "text": { "type": ["string", "null"], "maxLength": 10000 }, "verification": { "type": ["string", "null"], "enum": ["verified", "corrected", "recovered", "unverified", null] }, "verification_score": { "type": ["number", "null"] }, "source_type": { "type": ["string", "null"] }, "page": { "type": ["string", "null"], "maxLength": 10000 }, "section_title": { "type": ["string", "null"], "maxLength": 10000 }, "context_before": { "type": ["string", "null"], "maxLength": 10000 }, "context_after": { "type": ["string", "null"], "maxLength": 10000 }, "original_quote": { "type": ["string", "null"], "maxLength": 10000 }, "available": { "type": "boolean", "enum": [false] }, "reason": { "type": "string", "enum": ["source_unavailable"] } }, "required": [ "source_ref", "citation_id", "title", "quote", "text", "verification", "verification_score", "source_type", "page", "section_title", "context_before", "context_after", "original_quote", "available", "reason" ] } ] } } }, "required": ["ref", "title", "description", "key_questions", "citations"] }, "description": "The topics applying creates." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "description": "Stable within this proposal, e.g. G1." }, "kind": { "type": "string", "enum": ["single_alert", "similar_alerts", "replacement_set"] }, "topic_ref": { "type": "string", "description": "The proposed topic the group goes to." }, "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "source_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The topics the alerts are in now." }, "title": { "type": "string", "description": "Title of a representative alert." }, "message": { "type": "string", "description": "Explanation of a representative alert." }, "line_item": { "type": ["string", "null"] }, "pricing": { "type": ["string", "null"] } }, "required": [ "ref", "kind", "topic_ref", "alert_ids", "source_topic_ids", "title", "message", "line_item", "pricing" ] }, "description": "Alerts that move together. Every alert of the selected topics is in one group." }, "warnings": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "applied_at": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "id", "agreement_id", "operation", "topic_ids", "instructions", "topics", "groups", "warnings", "created_at", "applied_at" ] }, "AlertTopicProposalResult": { "type": "object", "properties": { "created_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "deleted_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "moved_alert_count": { "type": "integer", "minimum": 0 } }, "required": ["created_topic_ids", "deleted_topic_ids", "moved_alert_count"] }, "Agreement": { "allOf": [ { "$ref": "#/components/schemas/AgreementSummary" }, { "type": "object", "properties": { "applicability": { "type": ["object", "null"], "properties": { "match": { "type": "string", "enum": ["all", "any"] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["contains"] }, "value": { "type": "string" } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["not_contains"] }, "value": { "type": "string" } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["in"] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": ["field", "operator", "values"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["not_in"] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": ["field", "operator", "values"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["is_empty"] } }, "required": ["field", "operator"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["is_not_empty"] } }, "required": ["field", "operator"], "additionalProperties": false } ] }, "minItems": 1 } }, "required": ["match", "conditions"], "additionalProperties": false, "description": "Additional invoice-matching conditions over reference and delivery fields. Included in agreement detail; omitted from list summaries. Null means no additional conditions. Existing values retain whitespace and may exceed current write limits; unsupported stored conditions return 409." }, "renewal": { "type": ["object", "null"], "properties": { "mode": { "type": ["string", "null"], "enum": ["none", "optional", "automatic", null], "default": null }, "period": { "type": ["object", "null"], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "unit": { "type": "string", "enum": ["days", "weeks", "months", "years"] } }, "default": null, "required": ["value", "unit"], "additionalProperties": false }, "occurrences_remaining": { "type": ["integer", "null"], "minimum": 0, "maximum": 2147483647, "default": null }, "notice_period": { "type": ["object", "null"], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "unit": { "type": "string", "enum": ["days", "weeks", "months", "years"] } }, "default": null, "required": ["value", "unit"], "additionalProperties": false }, "deadline_override": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "additionalProperties": false }, "instructions": { "type": ["string", "null"], "description": "Additional context used when interpreting this agreement during compliance checks." }, "alert_settings": { "type": "object", "properties": { "flag_undercharges": { "type": "boolean", "default": false }, "flag_uncovered_items": { "type": "boolean", "default": false } }, "additionalProperties": false, "description": "Agreement-specific alert preferences. Replaces the complete object; omitted flags default to false. Saving preferences does not run checks." }, "matching_settings": { "type": "object", "properties": { "smart_matching_enabled": { "type": "boolean", "default": false }, "smart_matching_criterion": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "default": null } }, "additionalProperties": false, "description": "Stored smart-matching configuration. Replaces the complete object; omitted values default to false and null. Saving does not run matching." } }, "required": [ "applicability", "renewal", "instructions", "alert_settings", "matching_settings" ] } ] }, "Error_conflict_source_unavailable": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["conflict", "source_unavailable"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "AgreementPriceItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "description": { "type": ["string", "null"] }, "product_code": { "type": ["string", "null"] }, "product_group": { "type": ["string", "null"] }, "unit": { "type": ["string", "null"] }, "currency_code": { "type": ["string", "null"] }, "price": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["amount"] }, "amount": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["type", "amount"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["rate"] }, "fraction": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "basis": { "type": ["string", "null"] } }, "required": ["type", "fraction", "basis"] } ] }, "discount_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "vat_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "applicability": { "type": ["string", "null"] }, "calculation_rules": { "type": ["string", "null"] }, "valid_from": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "valid_until": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "source": { "type": ["object", "null"], "properties": { "price_import_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" } }, "required": ["price_import_id", "document_id", "file_name"], "description": "The price import that created this price and the Document it read. Null for prices created otherwise." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agreement_id", "position", "description", "product_code", "product_group", "unit", "currency_code", "price", "discount_rate", "surcharge_rate", "vat_rate", "applicability", "calculation_rules", "valid_from", "valid_until", "source", "created_at", "updated_at" ] }, "AgreementPriceImport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid", "description": "The Document the prices were extracted from." }, "worksheets": { "type": ["array", "null"], "items": { "type": "string" } }, "instructions": { "type": ["string", "null"] }, "default_currency": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["queued", "running", "completed", "failed", "cancelled"], "description": "completed means the new prices are appended and the price table is written, in one transaction. Failed and cancelled imports append nothing." }, "counts": { "type": ["object", "null"], "properties": { "created": { "type": "integer", "minimum": 0, "description": "Rows appended as new prices." }, "duplicate": { "type": "integer", "minimum": 0, "description": "Rows with the same product and price as an existing price or an earlier row, and not appended." }, "invalid": { "type": "integer", "minimum": 0, "description": "Rows that fail the price rules, recorded with their errors and not appended." } }, "required": ["created", "duplicate", "invalid"], "description": "Row outcomes, set when the import completes; null before and on failure." }, "failure": { "type": ["object", "null"], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": ["code", "message"], "description": "extraction_incomplete, extraction_failed, agreement_busy or agreement_deleted. dispatch_failed or admission_expired: processing never started. execution_incomplete: processing ended without a result. Import again in every case." }, "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agreement_id", "document_id", "worksheets", "instructions", "default_currency", "status", "counts", "failure", "workflow_run_id", "workflow_run_item_id", "created_at", "updated_at" ] }, "Error_unsupported_media_type": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unsupported_media_type"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "AgreementDocument": { "type": "object", "properties": { "agreement_id": { "type": "string", "format": "uuid" }, "document": { "$ref": "#/components/schemas/Document" }, "role": { "type": "string", "enum": ["terms", "price_list", "uncategorized", "excluded"] }, "position": { "type": ["integer", "null"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["agreement_id", "document", "role", "position", "created_at", "updated_at"] }, "ContextSuggestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": ["replace", "insert", "delete"], "description": "replace swaps anchor_text for proposed_text; insert adds proposed_text after anchor_text, or appends it as a new paragraph when anchor_text is empty; delete removes anchor_text." }, "anchor_text": { "type": "string", "description": "The verbatim span of the current instructions the edit applies to. It occurs exactly once in the instructions; empty only for an append." }, "proposed_text": { "type": ["string", "null"], "description": "The new text. Null for delete." }, "comment": { "type": "string", "description": "Why the edit is suggested, grounded in the dismissals." }, "created_at": { "type": "string", "format": "date-time" }, "evidence": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Dismissed alerts behind the suggestion." }, "items": { "type": "array", "items": { "type": "object", "properties": { "alert_id": { "type": ["string", "null"], "format": "uuid", "description": "The dismissed alert. A later check or reset may since have deleted it." }, "alert_title": { "type": ["string", "null"], "description": "Alert title at dismissal." }, "category": { "type": ["string", "null"], "enum": [ "wrong_alert", "valid_not_actioning", "already_handled", "duplicate_covered", "other", null ] }, "note": { "type": ["string", "null"] }, "dismissed_at": { "type": "string", "format": "date-time" } }, "required": ["alert_id", "alert_title", "category", "note", "dismissed_at"] }, "description": "The 20 most recent dismissed alerts behind the suggestion, newest first." } }, "required": ["total", "items"], "description": "The dismissals that produced the suggestion." } }, "required": [ "id", "operation", "anchor_text", "proposed_text", "comment", "created_at", "evidence" ] }, "Error_content_not_ready_source_unavailable": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["content_not_ready", "source_unavailable"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "Error_extraction_in_progress_source_unavailable_conflict": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["extraction_in_progress", "source_unavailable", "conflict"] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "description": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "maxItems": 20 }, "workflow_run_id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "existing_party": { "type": "object", "properties": { "type": { "type": "string", "enum": ["supplier", "recipient"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] } }, "required": ["code", "message", "request_id"] } }, "required": ["error"] }, "InvoiceImportSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["queued", "running", "completed", "failed", "cancelled"] }, "origin": { "type": "string", "enum": ["upload", "api", "email", "integration"], "description": "Channel that submitted the source. Provenance carries the actor or integration detail." }, "supersedes_invoice": { "type": "boolean", "description": "True when publication replaces an existing invoice from the same source." }, "deleted_at": { "type": ["string", "null"], "format": "date-time" }, "primary_document": { "anyOf": [{ "$ref": "#/components/schemas/Document" }, { "type": "null" }] }, "source_count": { "type": "integer", "minimum": 0 }, "attachment_count": { "type": "integer", "minimum": 0 }, "retryable": { "type": "boolean", "description": "Database eligibility for failed or cancelled import retry; source bytes are checked at admission." }, "provenance": { "type": "object", "properties": { "uploader": { "type": ["object", "null"], "properties": { "user_id": { "type": "string" }, "name": { "type": ["string", "null"] } }, "required": ["user_id", "name"] }, "api_key": { "type": ["object", "null"], "properties": { "name": { "type": "string" } }, "required": ["name"] }, "email": { "type": ["object", "null"], "properties": { "sender": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] } }, "required": ["sender", "name"] }, "integration": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["id", "name", "type"] } }, "required": ["uploader", "api_key", "email", "integration"] }, "classification_reason": { "type": ["string", "null"] }, "outcome": { "type": ["string", "null"], "enum": ["imported", "duplicate", "not_invoice", null] }, "invoice_id": { "type": ["string", "null"], "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" }, "failure": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "origin", "supersedes_invoice", "deleted_at", "primary_document", "source_count", "attachment_count", "retryable", "provenance", "classification_reason", "outcome", "invoice_id", "workflow_run_id", "workflow_run_item_id", "failure", "created_at", "updated_at" ] }, "InvoiceImport": { "allOf": [ { "$ref": "#/components/schemas/InvoiceImportSummary" }, { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "role": { "type": "string", "enum": ["primary", "attachment"] }, "position": { "type": "integer" } }, "required": ["document", "role", "position"] } }, "sources_next_cursor": { "type": ["string", "null"] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": ["inspection", "header", "lines", "xml"] }, "succeeded": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "confidence_level": { "type": ["string", "null"], "enum": ["high", "mid", "low", null] }, "confidence_reason": { "type": ["string", "null"], "maxLength": 2000 } }, "required": [ "stage", "succeeded", "created_at", "confidence_level", "confidence_reason" ] }, "maxItems": 4, "description": "Latest recorded result for each extraction stage, including reusable results from earlier executions. This is a bounded summary, not an execution history." } }, "required": ["sources", "sources_next_cursor", "evidence"] } ] }, "Invoice": { "allOf": [ { "$ref": "#/components/schemas/InvoiceSummary" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "linked_credit_note_count": { "type": "integer", "minimum": 0, "description": "Recorded credit notes linked to an ordinary or self-billed invoice." }, "matched_invoice_count": { "type": "integer", "minimum": 0, "description": "Recorded invoices matched from a credit note." }, "line_item_count": { "type": "integer", "description": "Stored line items; retrieve through the paginated line-items endpoint." }, "document_count": { "type": "integer", "description": "Linked source Documents; retrieve through the paginated documents endpoint." }, "agreement_match_count": { "type": "integer", "description": "Current organization-owned, nondeleted agreement matches across the invoice." }, "alert_count": { "type": "integer", "description": "Retained alerts in alert_summary.scope, including dismissed and outdated findings." } }, "required": [ "linked_credit_note_count", "matched_invoice_count", "line_item_count", "document_count", "agreement_match_count", "alert_count" ] }, "supplier_snapshot": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "organization_number": { "type": ["string", "null"] }, "main_name": { "type": ["string", "null"] }, "department": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] }, "website": { "type": ["string", "null"] }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] }, "state": { "type": ["string", "null"] }, "postal_code": { "type": ["string", "null"] }, "country_code": { "type": ["string", "null"] } }, "required": ["street", "city", "state", "postal_code", "country_code"] } }, "required": [ "name", "organization_number", "main_name", "department", "email", "website", "address" ] }, "recipient_snapshot": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "organization_number": { "type": ["string", "null"] }, "main_name": { "type": ["string", "null"] }, "department": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] }, "website": { "type": ["string", "null"] }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] }, "state": { "type": ["string", "null"] }, "postal_code": { "type": ["string", "null"] }, "country_code": { "type": ["string", "null"] } }, "required": ["street", "city", "state", "postal_code", "country_code"] } }, "required": [ "name", "organization_number", "main_name", "department", "email", "website", "address" ] }, "payment_terms": { "type": ["string", "null"], "description": "Stored printed payment terms, including conditions. Null means unavailable; never inferred from the due date." }, "invoice_note": { "type": ["string", "null"], "description": "Stored invoice-wide note in its original wording, separate from line notes. Null means unavailable; empty text stays empty." }, "additional_properties": { "type": ["array", "null"], "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "source_path": { "type": ["string", "null"] }, "scheme": { "type": ["string", "null"] } }, "required": ["name", "value"] }, "description": "Stored named business details with optional source paths. Null means unavailable; [] means inspected with none found. These do not replace financial values." }, "original_currency_code": { "type": ["string", "null"] }, "currency_conversion_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "original_total_amount_including_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "payment": { "type": "object", "properties": { "reference": { "type": ["string", "null"] }, "bank_account_number": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["paid", "unpaid", "unknown"] }, "outstanding_amount": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "override": { "type": ["object", "null"], "properties": { "outstanding_amount": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" } }, "required": ["outstanding_amount"] }, "integration_outstanding_amount": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" } }, "required": [ "reference", "bank_account_number", "status", "outstanding_amount", "override", "integration_outstanding_amount" ] }, "delivery": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] }, "state": { "type": ["string", "null"] }, "postal_code": { "type": ["string", "null"] }, "country_code": { "type": ["string", "null"] } }, "required": ["street", "city", "state", "postal_code", "country_code"] }, "date": { "type": ["string", "null"], "format": "date" } }, "required": ["name", "address", "date"] }, "references": { "type": "object", "properties": { "order_references": { "type": "array", "items": { "type": "string" } }, "buyer_reference": { "type": ["string", "null"] }, "seller_reference": { "type": ["string", "null"] }, "contract_reference": { "type": ["string", "null"] }, "project_reference": { "type": ["string", "null"] }, "accounting_cost": { "type": ["string", "null"] }, "credit_note_invoice_reference": { "type": ["string", "null"] } }, "required": [ "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "credit_note_invoice_reference" ] }, "origin": { "type": "object", "properties": { "type": { "type": "string", "enum": ["structured", "documents", "integration", "unknown"] }, "import_id": { "type": ["string", "null"], "format": "uuid", "description": "Creating import ID, when recorded. Excludes duplicate submissions." }, "source_system": { "type": ["string", "null"] }, "source_invoice_id": { "type": ["string", "null"] } }, "required": ["type", "import_id", "source_system", "source_invoice_id"] } }, "required": [ "payment_terms", "invoice_note", "additional_properties", "original_currency_code", "currency_conversion_rate", "original_total_amount_including_vat", "payment", "delivery", "references", "origin" ] } ] }, "InvoiceLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": "integer" }, "description": { "type": ["string", "null"] }, "product_code": { "type": ["string", "null"] }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "unit": { "type": ["string", "null"] }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "original_quantity": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "original_unit_price": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "original_total_excluding_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "original_line_number": { "type": ["integer", "null"] }, "period_start": { "type": ["string", "null"], "format": "date" }, "period_end": { "type": ["string", "null"], "format": "date" }, "notes": { "type": ["string", "null"], "description": "Stored notes field. Separate from printed line_note; neither field falls back to the other." }, "line_note": { "type": ["string", "null"], "description": "Stored printed line note, preserving original wording and empty text. Null means unavailable." }, "additional_properties": { "type": ["array", "null"], "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "source_path": { "type": ["string", "null"] }, "scheme": { "type": ["string", "null"] } }, "required": ["name", "value"] }, "description": "Stored named business details with optional source paths. Null means unavailable; [] means inspected with none found. These do not replace financial values." }, "allowance_charges": { "type": ["array", "null"], "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["price", "line", "document"] }, "is_charge": { "type": "boolean" }, "amount": { "type": ["number", "null"] }, "currency": { "type": ["string", "null"] }, "reason": { "type": ["string", "null"] }, "reason_code": { "type": ["string", "null"] }, "base_amount": { "type": ["number", "null"] }, "percentage": { "type": ["number", "null"] }, "source_path": { "type": ["string", "null"] } }, "required": ["scope", "is_charge", "amount"] }, "description": "Source allowance/charge evidence with optional source paths. Amounts retain their stored JSON number representation; do not post them as additional financial amounts. Null means unavailable; [] means inspected with none found." }, "financially_valid": { "type": "boolean", "readOnly": true, "description": "Deterministic arithmetic within a tolerance of 1 currency unit. Does not imply extraction accuracy, compliance, or human approval." }, "financial_errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_financial_inputs", "line_calculation_mismatch", "invoice_total_mismatch", "invoice_subtotal_mismatch", "category_amount_mismatch" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] }, "readOnly": true } }, "required": [ "id", "line_number", "description", "product_code", "quantity", "unit", "unit_price", "discount_rate", "surcharge_rate", "vat_rate", "total_excluding_vat", "original_quantity", "original_unit_price", "original_total_excluding_vat", "original_line_number", "period_start", "period_end", "notes", "line_note", "additional_properties", "allowance_charges", "financially_valid", "financial_errors" ] }, "InvoiceCorrectionValue": { "type": ["string", "number", "boolean", "null", "array", "object"], "items": { "$ref": "#/components/schemas/InvoiceCorrectionValue" }, "additionalProperties": { "$ref": "#/components/schemas/InvoiceCorrectionValue" } }, "MatchedInvoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": ["string", "null"] }, "title": { "type": ["string", "null"] }, "category": { "type": "string", "enum": ["invoice", "credit_note", "self_billed_invoice"] }, "issued_date": { "type": ["string", "null"], "format": "date" }, "currency_code": { "type": ["string", "null"] }, "total_amount_including_vat": { "type": ["string", "null"] }, "total_amount_excluding_vat": { "type": ["string", "null"] }, "supplier_name": { "type": ["string", "null"], "description": "Current canonical supplier name." }, "deleted_at": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "id", "invoice_number", "title", "category", "issued_date", "currency_code", "total_amount_including_vat", "total_amount_excluding_vat", "supplier_name", "deleted_at" ] }, "match_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "active": { "type": "boolean" } }, "required": ["id", "invoice", "match_type", "created_at", "active"] }, "OrganizationSummary": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string" } }, "required": ["id", "name"] }, "Team": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "references": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": ["string", "null"] }, "missing": { "type": "boolean" }, "type": { "type": "string", "enum": ["supplier", "recipient", "agreement", "agreement_tag"] } }, "required": ["id", "name", "missing", "type"] } }, "filter": { "$ref": "#/components/schemas/StoredSubscriptionFilter" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "name", "filter", "created_at", "updated_at", "references"] }, "CreateTeam": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "filter": { "type": ["object", "null"], "properties": { "schema_version": { "type": "number", "enum": [1] }, "root": { "$ref": "#/components/schemas/TeamFilterRoot" } }, "required": ["schema_version", "root"], "additionalProperties": false, "description": "Omit to preserve the filter on PATCH, send null to clear it, or supply a complete version-1 definition to replace it. No saved filter matches no records." }, "user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 100 } }, "required": ["name"], "additionalProperties": false }, "UpdateTeam": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "filter": { "type": ["object", "null"], "properties": { "schema_version": { "type": "number", "enum": [1] }, "root": { "$ref": "#/components/schemas/TeamFilterRoot" } }, "required": ["schema_version", "root"], "additionalProperties": false, "description": "Omit to preserve the filter on PATCH, send null to clear it, or supply a complete version-1 definition to replace it. No saved filter matches no records." } }, "additionalProperties": false }, "TeamMember": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "first_name": { "type": ["string", "null"] }, "last_name": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] } }, "required": ["user_id", "first_name", "last_name", "email"] }, "AddTeamMember": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["user_id"], "additionalProperties": false }, "PartyMergeResult": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Party" }, "workflow_run_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "merged_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "affected_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "invoices_moved": { "type": "integer", "minimum": 0 } }, "required": [ "target", "workflow_run_ids", "merged_ids", "affected_agreement_ids", "invoices_moved" ] }, "Party": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_number": { "type": ["string", "null"] }, "org_country": { "type": ["string", "null"], "description": "Country issuing the organization number; null when unknown." }, "email": { "type": ["string", "null"] }, "website": { "type": ["string", "null"] }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] }, "state": { "type": ["string", "null"] }, "postal_code": { "type": ["string", "null"] }, "country_code": { "type": ["string", "null"] } }, "required": ["street", "city", "state", "postal_code", "country_code"] }, "domain": { "type": ["string", "null"], "description": "Derived company domain; not editable." }, "relationships": { "type": "object", "properties": { "invoice_count": { "type": "integer", "minimum": 0 }, "agreement_count": { "type": "integer", "minimum": 0 }, "pending_alert_count": { "type": "integer", "minimum": 0 }, "blocking_invoice_count": { "type": "integer", "minimum": 0 }, "blocking_agreement_count": { "type": "integer", "minimum": 0 }, "can_delete": { "type": "boolean" } }, "required": [ "invoice_count", "agreement_count", "pending_alert_count", "blocking_invoice_count", "blocking_agreement_count", "can_delete" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "organization_number", "org_country", "email", "website", "address", "domain", "relationships", "created_at", "updated_at" ] }, "PartyDirectoryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Party" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] }, "total_count": { "type": "integer", "minimum": 0 } }, "required": ["data", "next_cursor", "total_count"] }, "CreateParty": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 500 }, "organization_number": { "type": ["string", "null"], "maxLength": 100, "description": "Registration identifier, at most 100 characters. Recognized country-specific formats and checksums are validated using the registration country, recognized prefix, or address country. Valid identifiers are stored canonically, preserving leading zeros and identifier families. Invalid supported identifiers and placeholders are rejected. Unsupported and format-only identifiers receive basic character validation without country inference. Null or blank clears the number." }, "org_country": { "type": ["string", "null"], "pattern": "^([A-Za-z]{2})?$", "description": "Country issuing the organization number. Missing countries are inferred only after checksum validation, using a recognized prefix before the address country. Existing countries are preserved unless explicitly changed. Null clears the country and suppresses inference for this write; later ingestion may infer it again." }, "email": { "type": ["string", "null"], "maxLength": 320 }, "website": { "type": ["string", "null"], "maxLength": 2000 }, "address": { "type": ["object", "null"], "properties": { "street": { "type": ["string", "null"], "maxLength": 2000 }, "city": { "type": ["string", "null"], "maxLength": 2000 }, "state": { "type": ["string", "null"], "maxLength": 2000 }, "postal_code": { "type": ["string", "null"], "maxLength": 2000 }, "country_code": { "type": ["string", "null"], "pattern": "^([A-Za-z]{2})?$" } }, "additionalProperties": false } }, "required": ["name"], "additionalProperties": false }, "UpdateParty": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 500 }, "organization_number": { "type": ["string", "null"], "maxLength": 100, "description": "Registration identifier, at most 100 characters. Recognized country-specific formats and checksums are validated using the registration country, recognized prefix, or address country. Valid identifiers are stored canonically, preserving leading zeros and identifier families. Invalid supported identifiers and placeholders are rejected. Unsupported and format-only identifiers receive basic character validation without country inference. Null or blank clears the number." }, "org_country": { "type": ["string", "null"], "pattern": "^([A-Za-z]{2})?$", "description": "Country issuing the organization number. Missing countries are inferred only after checksum validation, using a recognized prefix before the address country. Existing countries are preserved unless explicitly changed. Null clears the country and suppresses inference for this write; later ingestion may infer it again." }, "email": { "type": ["string", "null"], "maxLength": 320 }, "website": { "type": ["string", "null"], "maxLength": 2000 }, "address": { "type": ["object", "null"], "properties": { "street": { "type": ["string", "null"], "maxLength": 2000 }, "city": { "type": ["string", "null"], "maxLength": 2000 }, "state": { "type": ["string", "null"], "maxLength": 2000 }, "postal_code": { "type": ["string", "null"], "maxLength": 2000 }, "country_code": { "type": ["string", "null"], "pattern": "^([A-Za-z]{2})?$" } }, "additionalProperties": false } }, "additionalProperties": false }, "WorkflowRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "One operation containing zero or more work items. Explicit retry creates a new run." }, "retry_of_run_id": { "type": ["string", "null"], "format": "uuid" }, "type": { "type": "string", "enum": [ "organization_currency_conversion", "document_extraction", "agreement_document_classification", "agreement_detail_suggestions", "invoice_import", "invoice_import_batch", "invoice_agreement_matching", "agreement_invoice_matching", "invoice_compliance_check", "agreement_compliance_check", "integration_sync", "alert_topic_reconciliation", "alert_topic_proposal", "agreement_context_suggestions", "agreement_price_import" ] }, "resource": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invoice_import", "workflow_run", "invoice", "agreement", "document", "integration", "agreement_price_import" ] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"], "description": "The business operation owning this execution; for invoice_import, the InvoiceImport." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "completed_with_errors", "failed", "cancelled" ] }, "progress": { "type": "object", "properties": { "total": { "type": ["integer", "null"], "minimum": 0 }, "queued": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "required": [ "total", "queued", "running", "completed", "skipped", "failed", "cancelled" ], "description": "Counts of admitted items. total is null while more items may be discovered." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last product state change, excluding internal provider checks." }, "started_at": { "type": ["string", "null"], "format": "date-time" }, "finished_at": { "type": ["string", "null"], "format": "date-time" }, "failure": { "type": ["object", "null"], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": ["code", "message"] } }, "required": [ "id", "retry_of_run_id", "type", "resource", "status", "progress", "created_at", "updated_at", "started_at", "finished_at", "failure" ] }, "WorkflowRunSummary": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowSummaryEntry" } } }, "required": ["data"] }, "WorkflowSummaryEntry": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization_currency_conversion", "document_extraction", "agreement_document_classification", "agreement_detail_suggestions", "invoice_import", "invoice_import_batch", "invoice_agreement_matching", "agreement_invoice_matching", "invoice_compliance_check", "agreement_compliance_check", "integration_sync", "alert_topic_reconciliation", "alert_topic_proposal", "agreement_context_suggestions", "agreement_price_import" ] }, "run_counts": { "type": "object", "properties": { "queued": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "completed_with_errors": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "required": [ "queued", "running", "completed", "completed_with_errors", "failed", "cancelled" ], "description": "Counts of all retained public runs, including terminal runs." }, "progress": { "type": "object", "properties": { "total": { "type": ["integer", "null"], "minimum": 0 }, "queued": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "required": [ "total", "queued", "running", "completed", "skipped", "failed", "cancelled" ], "description": "Item progress for currently active runs only. Total is null while discovery remains open." }, "discovering_run_count": { "type": "integer", "minimum": 0 }, "change_token": { "type": "string", "description": "Opaque snapshot token covering run counts and active item progress, including completion after runs disappear. Not an event cursor." } }, "required": ["type", "run_counts", "progress", "discovering_run_count", "change_token"] }, "WorkflowRunItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "run_id": { "type": "string", "format": "uuid" }, "retry_of_item_id": { "type": ["string", "null"], "format": "uuid" }, "resource": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invoice_import", "workflow_run", "invoice", "agreement", "document", "integration", "agreement_price_import" ] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["source_invoice"] }, "id": { "type": "string", "minLength": 1 } }, "required": ["type", "id"], "description": "An invoice in the accounting system, by its provider-owned key." } ] }, "status": { "type": "string", "enum": ["queued", "running", "completed", "skipped", "failed", "cancelled"] }, "result": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["organization_currency_conversion"] }, "updated": { "type": "integer", "minimum": 0 }, "missing_rates": { "type": "integer", "minimum": 0 } }, "required": ["type", "updated", "missing_rates"] }, { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_import"] }, "outcome": { "type": "string", "enum": ["imported"] }, "invoice_id": { "type": "string", "format": "uuid" } }, "required": ["type", "outcome", "invoice_id"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_import"] }, "outcome": { "type": "string", "enum": ["duplicate"] }, "invoice_id": { "type": "string", "format": "uuid" } }, "required": ["type", "outcome", "invoice_id"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_import"] }, "outcome": { "type": "string", "enum": ["not_invoice"] }, "classification_reason": { "type": ["string", "null"] }, "invoice_id": { "type": "null" } }, "required": ["type", "outcome", "invoice_id"] } ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_import_admission"] }, "outcome": { "type": "string", "enum": ["duplicate", "capacity_rejected"] }, "invoice_id": { "type": ["string", "null"], "format": "uuid" } }, "required": ["type", "outcome", "invoice_id"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_agreement_matching"] }, "invoice_id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": ["string", "null"], "format": "uuid" }, "matched_count": { "type": "integer", "minimum": 0 }, "created_count": { "type": "integer", "minimum": 0 }, "removed_count": { "type": "integer", "minimum": 0 }, "relationship_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "relationships_url": { "type": "string" } }, "required": [ "type", "invoice_id", "agreement_id", "matched_count", "created_count", "removed_count", "relationship_ids", "relationships_url" ] }, { "type": "object", "properties": { "source_version": { "type": "string" }, "strategy": { "type": "string", "enum": ["datalab", "deterministic"] }, "verification": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["verified", "skipped", "error"] }, "reason": { "type": ["string", "null"], "maxLength": 100 }, "issue_count": { "type": "integer", "minimum": 0 }, "dropped_correction_count": { "type": "integer", "minimum": 0 } }, "required": ["outcome", "reason", "issue_count", "dropped_correction_count"] }, "type": { "type": "string", "enum": ["document_extraction"] }, "document_id": { "type": "string", "format": "uuid" }, "requested_strategy": { "type": "string", "enum": ["datalab", "deterministic"] }, "fallback_strategy": { "type": ["string", "null"], "enum": ["datalab", "deterministic", null] }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "source_version", "strategy", "verification", "type", "document_id", "requested_strategy", "fallback_strategy", "limitations" ] }, { "type": "object", "properties": { "role": { "type": ["string", "null"], "enum": ["terms", "price_list", "excluded", null] }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "suggested_import_context": { "type": ["string", "null"], "maxLength": 120 }, "type": { "type": "string", "enum": ["agreement_document_classification"] }, "document_id": { "type": "string", "format": "uuid" } }, "required": ["role", "reason", "suggested_import_context", "type", "document_id"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["agreement_detail_suggestions"] }, "document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 10 }, "suggestions": { "type": "object", "properties": { "title": { "type": ["string", "null"], "minLength": 1, "maxLength": 500 }, "effective_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "expiration_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "renewal": { "type": ["object", "null"], "properties": { "mode": { "type": ["string", "null"], "enum": ["none", "optional", "automatic", null], "default": null }, "period": { "type": ["object", "null"], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "unit": { "type": "string", "enum": ["days", "weeks", "months", "years"] } }, "default": null, "required": ["value", "unit"], "additionalProperties": false }, "occurrences_remaining": { "type": ["integer", "null"], "minimum": 0, "maximum": 2147483647, "default": null }, "notice_period": { "type": ["object", "null"], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "unit": { "type": "string", "enum": ["days", "weeks", "months", "years"] } }, "default": null, "required": ["value", "unit"], "additionalProperties": false }, "deadline_override": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "additionalProperties": false }, "smart_matching_criterion": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000 }, "supplier": { "type": ["object", "null"], "properties": { "extracted": { "type": "object", "properties": { "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 500 }, "organization_number": { "type": ["string", "null"], "minLength": 1, "maxLength": 100 } }, "required": ["name", "organization_number"] }, "canonical": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_number": { "type": ["string", "null"] } }, "required": ["id", "name", "organization_number"] } }, "required": ["extracted", "canonical"] }, "recipient": { "type": ["object", "null"], "properties": { "extracted": { "type": "object", "properties": { "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 500 }, "organization_number": { "type": ["string", "null"], "minLength": 1, "maxLength": 100 } }, "required": ["name", "organization_number"] }, "canonical": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_number": { "type": ["string", "null"] } }, "required": ["id", "name", "organization_number"] } }, "required": ["extracted", "canonical"] } }, "required": [ "title", "effective_date", "expiration_date", "renewal", "smart_matching_criterion", "supplier", "recipient" ] } }, "required": ["type", "document_ids", "suggestions"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_compliance_check"] }, "compliance_check_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "finding_count": { "type": "integer", "minimum": 0 }, "completeness": { "type": "string", "enum": ["complete", "incomplete"] } }, "required": [ "type", "compliance_check_id", "invoice_id", "agreement_id", "finding_count", "completeness" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["agreement_compliance_check"] }, "compliance_check_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "finding_count": { "type": "integer", "minimum": 0 }, "completeness": { "type": "string", "enum": ["complete", "incomplete"] } }, "required": [ "type", "compliance_check_id", "invoice_id", "agreement_id", "finding_count", "completeness" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["alert_topic_reconciliation"] }, "agreement_id": { "type": "string", "format": "uuid" }, "topics_created": { "type": "integer", "minimum": 0 }, "topics_updated": { "type": "integer", "minimum": 0 }, "topics_deleted": { "type": "integer", "minimum": 0 }, "memberships_written": { "type": "integer", "minimum": 0 } }, "required": [ "type", "agreement_id", "topics_created", "topics_updated", "topics_deleted", "memberships_written" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["alert_topic_proposal"] }, "proposal_id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": ["merge", "split"] } }, "required": ["type", "proposal_id", "agreement_id", "operation"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["agreement_context_suggestions"] }, "agreement_id": { "type": "string", "format": "uuid" }, "suggestion_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "description": "Pending suggestions this dismissal produced, in note order. Empty when the dismissal warranted no edit or its edits no longer applied to the note." } }, "required": ["type", "agreement_id", "suggestion_ids"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["agreement_price_import"] }, "price_import_id": { "type": "string", "format": "uuid" }, "counts": { "type": "object", "properties": { "created": { "type": "integer", "minimum": 0, "description": "Rows appended as new prices." }, "duplicate": { "type": "integer", "minimum": 0, "description": "Rows with the same product and price as an existing price or an earlier row, and not appended." }, "invalid": { "type": "integer", "minimum": 0, "description": "Rows that fail the price rules, recorded with their errors and not appended." } }, "required": ["created", "duplicate", "invalid"] } }, "required": ["type", "price_import_id", "counts"] }, { "type": "null" } ], "description": "Immutable, bounded business result. null until completed or skipped; failed/cancelled items have no result." }, "failure": { "type": ["object", "null"], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": ["code", "message"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": ["string", "null"], "format": "date-time" }, "finished_at": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "id", "run_id", "retry_of_item_id", "resource", "status", "result", "failure", "created_at", "updated_at", "started_at", "finished_at" ] } }, "parameters": {} }, "paths": { "/v1/notifications/preferences": { "get": { "operationId": "getNotificationPreferences", "summary": "Read notification preferences", "tags": ["Notifications"], "description": "Returns personal and organization preference groups with channel ID references, event selections, enablement and readiness, without creating any rows. Channel destinations are read separately from channels. Personal means the caller in the selected organization. Personal scope is shared across channels; mine includes usable personal and team sources, and no usable source pauses delivery. Organization scope is always organization and its sources are empty. Both groups are returned even when they have no channels.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Personal and organization preferences in the selected organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferencesDocument" }, "example": { "preferences": [ { "owner": "personal", "scope": "organization", "sources": [], "channels": [] }, { "owner": "organization", "scope": "organization", "sources": [], "channels": [] } ] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateNotificationPreferences", "summary": "Update notification preferences", "tags": ["Notifications"], "description": "Choose owner in the JSON body: personal changes require Write, organization changes require Admin. Updates scope and channel settings atomically; any failure rolls back the entire request. Scope is personal-only and shared across personal channels. Omitted channels and fields are preserved; supplied events replace selections without changing enablement. Channel IDs must be unique and belong to the selected owner. Personal email updates refresh the verified primary address. The first personal save retains the disabled email anchor. Scope edits affect future scheduling.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationPreferences" } } } }, "responses": { "200": { "description": "Updated owner preference group.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/notifications/channels": { "get": { "operationId": "listNotificationChannels", "summary": "List notification channels", "tags": ["Notifications"], "description": "Lists destinations and connections for the caller’s personal channels and organization channels. Delivery settings and readiness belong to preferences. No default rows are created. Delivery summaries count delivered event content in the last 30 days, not provider messages.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": ["personal", "organization"] }, "required": false, "name": "owner", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Channels ordered by ID.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannel" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createNotificationChannel", "summary": "Create a notification channel", "tags": ["Notifications"], "description": "Currently supports type email: creates the caller’s personal channel disabled with no selected events, using the verified primary account address. Repeated requests return the existing channel unchanged. Shared email creation and other channel types are not supported.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationChannel" } } } }, "responses": { "200": { "description": "Notification destination and connection. Delivery settings are in preferences; credentials are never returned.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationChannel" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/notifications/channels/slack/authorize": { "post": { "operationId": "authorizeNotificationSlack", "summary": "Start a Slack notification connection", "tags": ["Notifications"], "description": "Choose owner personal or organization. Sessions and personal API keys receive a setup link for the existing settings screen. Organization connections require Admin. The initiating user opens the link while signed in to the selected organization. The browser calls this endpoint with the setup token and a fresh browser_nonce to receive the Slack consent URL. Browser consent requires a Clerk session. Links expire after ten minutes; connecting never selects new events.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "type": "string", "enum": ["personal", "organization"] }, "setup_token": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Setup token from the agent-created link; browser use only." }, "browser_nonce": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Random 32-byte hex nonce retained in browser session storage. Requires a Clerk session." } }, "required": ["owner"], "additionalProperties": false, "anyOf": [ { "not": { "required": ["setup_token"] } }, { "required": ["browser_nonce"] } ] } } } }, "responses": { "200": { "description": "Browser authorization URL and expiry.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "required": ["expires_at", "url"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/notifications/channels/slack/complete": { "post": { "operationId": "completeNotificationSlack", "summary": "Complete Slack connection", "tags": ["Notifications"], "description": "Requires the initiating user’s Clerk session with the same active organization. Current membership, MFA, owner permission and initiating API-key authority are rechecked explicitly. State must match the initiating browser session and nonce. Slack codes are single-use; failed, repeated or expired completion requires a new attempt. No pending authorization or completion result is stored.", "parameters": [], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "minLength": 1, "maxLength": 4096 }, "code": { "type": "string", "minLength": 1, "maxLength": 2048 }, "browser_nonce": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": ["state", "code", "browser_nonce"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Notification destination and connection. Delivery settings are in preferences; credentials are never returned.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationChannel" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/notifications/channels/{id}": { "get": { "operationId": "getNotificationChannel", "summary": "Read a notification channel", "tags": ["Notifications"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Notification destination and connection. Delivery settings are in preferences; credentials are never returned.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationChannel" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteNotificationChannel", "summary": "Disconnect a notification channel", "tags": ["Notifications"], "description": "Organization channels require Admin access. Personal email must be disabled instead of deleted. Explicit deletion retains the existing cascade: queued events and delivery history belonging to this channel are removed.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Channel disconnected." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/notifications/channels/{id}/test": { "post": { "operationId": "testNotificationChannel", "summary": "Send test notification", "tags": ["Notifications"], "description": "Organization channels require Admin access. Tests work for configured disabled or paused channels and never change preferences, selections or event history. Personal email destinations must still be verified on the caller’s account. The provider accepted the send; delivery is not guaranteed. Retrying may send another test.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Provider accepted the test notification.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true] } }, "required": ["success"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The channel or authorization cannot accept this operation. Read the error description before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/search": { "get": { "operationId": "searchObjects", "summary": "Search product records", "tags": ["Search"], "description": "Ranked, organization-scoped search for command palettes and mentions across agreements, invoices, alerts, topics and claims. Exact matches precede prefixes and substrings, then recency breaks ties. Substring matching starts at three characters. Limits apply per type; no cursor is returned. Results include navigation identities, not frontend URLs. Agreement supplier names are display context, not searched text.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "query", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated entity types: agreement, invoice, alert, topic, claim. Omit to search all types." }, "required": false, "description": "Comma-separated entity types: agreement, invoice, alert, topic, claim. Omit to search all types.", "name": "types", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 }, "required": false, "name": "limit_per_type", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Ranked search results.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "type": { "type": "string", "enum": ["agreement"] }, "supplier_names": { "type": "array", "items": { "type": "string" } } }, "required": ["id", "title", "type", "supplier_names"] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "type": { "type": "string", "enum": ["invoice"] } }, "required": ["id", "title", "type"] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "type": { "type": "string", "enum": ["alert"] }, "status": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] } }, "required": ["id", "title", "type", "status"] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "type": { "type": "string", "enum": ["topic"] }, "agreement_id": { "type": "string", "format": "uuid" } }, "required": ["id", "title", "type", "agreement_id"] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "type": { "type": "string", "enum": ["claim"] } }, "required": ["id", "title", "type"] } ] }, "maxItems": 100 } }, "required": ["results"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/overview": { "get": { "operationId": "getOverview", "summary": "Get the organization overview", "tags": ["Overview"], "description": "Organization-wide Home summary and ordered next-step objects. Each step carries its own display counts and, for agreement actions, a singular agreement_id or null for list navigation. Setup and upload steps carry only type. Lifetime invoice spend is excluding VAT, including credit notes and future-dated invoices. Recent means the organization-local last seven calendar days including today; coverage uses trailing twelve months. Coverage is the fraction of checkable invoices matched to a ready agreement, not completed-check coverage. Money is returned as exact decimal strings; incomplete amounts remain null. Unchecked counts distinct checkable invoices with a primary document and at least one ready matched agreement without a completed or active check. Active checks include API invoice and agreement checks and legacy missing-check runs; POST /v1/agreements/check checks the unchecked invoices. as_of is the calculation time, not a retained database snapshot. This read does not initiate work.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Home metrics and next steps.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Overview" }, "example": { "as_of": "2026-09-18T12:00:00.000Z", "timezone": "Europe/Oslo", "organization_currency": "NOK", "periods": { "coverage": { "start": "2025-09-18", "end": "2026-09-18" }, "recent": { "start": "2026-09-12", "end": "2026-09-18" } }, "agreement_count": 8, "has_invoices": true, "invoice_spend": { "total": [{ "currency_code": "NOK", "amount": "250000.00" }], "recent": [{ "currency_code": "NOK", "amount": "12000.00" }] }, "claims": { "awaiting": { "total": [{ "currency_code": "NOK", "amount": "4000.00" }], "recent": [{ "currency_code": "NOK", "amount": "1000.00" }] }, "refunded": { "total": [{ "currency_code": "NOK", "amount": "2000.00" }], "recent": [{ "currency_code": "NOK", "amount": "500.00" }] } }, "alerts": { "pending": { "count": 4, "value": { "total": [{ "currency_code": "NOK", "amount": "3000.00" }], "recent": [{ "currency_code": "NOK", "amount": "750.00" }] } } }, "next_steps": [ { "type": "review_alerts", "count": 4 }, { "type": "finish_agreement", "count": 1, "agreement_id": "00000000-0000-4000-8000-000000000001" } ] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/support/contact": { "post": { "operationId": "contactSupport", "summary": "Contact support", "tags": ["Support"], "description": "Send a message to Watchdog support as the authenticated user in the current organization. Supports up to five base64 attachments of at most 4.5 MiB each; the entire JSON request is limited to 32 MiB. Success means the email provider accepted the message, not that delivery is complete. Supply an Idempotency-Key for retry protection for 24 hours; reuse it only with identical input. Without a key, an uncertain retry can send a duplicate.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 5000 }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^\\r\\n\\0]+$" }, "content": { "type": "string", "maxLength": 6300000 } }, "required": ["filename", "content"], "additionalProperties": false }, "maxItems": 5 } }, "required": ["message"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Message accepted for delivery.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true] } }, "required": ["success"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 32 MiB (33,554,432 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 32 MiB (33,554,432 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "The contact request key was reused with different input or is still being processed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The contact request key was reused with different input or is still being processed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/agreements": { "get": { "operationId": "listInvoiceAgreements", "summary": "List matched agreements", "tags": ["Invoices"], "description": "Persisted relationships ordered by creation time and UUID, ascending. Refreshing retains relationship IDs and does not change ordering. Archived agreements retain matches. Deleted agreements and deleted/non-completed invoices are excluded. These reads do not run matching or compliance.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A bounded page of matched relationships.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "last_matched_at": { "type": "string", "format": "date-time" }, "agreement": { "$ref": "#/components/schemas/AgreementSummary" } }, "required": [ "id", "invoice_id", "agreement_id", "created_at", "last_matched_at", "agreement" ] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/match-agreements": { "post": { "operationId": "matchInvoiceAgreements", "summary": "Refresh matched agreements", "tags": ["Invoices"], "description": "Explicitly refresh applicable relationships without starting compliance checks or approving invoices. A removed relationship deletes the alerts of that pair, unless a claim that is not cancelled holds one of them that is not dismissed, and cancels its unfinished checks; completed ComplianceChecks are kept. Each item represents one invoice and publishes atomically; other invoices can succeed independently. Every fresh command creates a new run and supersedes active API work for that target; unsuccessful predecessors are linked. An Idempotency-Key replay returns its original identity and never redispatches. Inactive agreements preserve relationships. Financial validity is not a matching gate.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Idempotent receipt replay.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "202": { "description": "Durably admitted and execution acceptance confirmed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Conflicting idempotency key or unavailable target.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Conflicting idempotency key or unavailable target.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Execution acceptance is unconfirmed. Follow Location to inspect the retained workflow run.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Execution acceptance is unconfirmed. Follow Location to inspect the retained workflow run.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/invoices": { "get": { "operationId": "listAgreementInvoices", "summary": "List matched invoices", "tags": ["Agreements"], "description": "Persisted relationships ordered by creation time and UUID, ascending. Refreshing retains relationship IDs and does not change ordering. Archived agreements retain matches. Deleted agreements and deleted/non-completed invoices are excluded. These reads do not run matching or compliance.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A bounded page of matched relationships.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "last_matched_at": { "type": "string", "format": "date-time" }, "invoice": { "$ref": "#/components/schemas/InvoiceSummary" } }, "required": [ "id", "invoice_id", "agreement_id", "created_at", "last_matched_at", "invoice" ] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/match-invoices": { "post": { "operationId": "matchAgreementInvoices", "summary": "Refresh matched invoices", "tags": ["Agreements"], "description": "Explicitly refresh applicable relationships without starting compliance checks or approving invoices. A removed relationship deletes the alerts of that pair, unless a claim that is not cancelled holds one of them that is not dismissed, and cancels its unfinished checks; completed ComplianceChecks are kept. Each item represents one invoice and publishes atomically; other invoices can succeed independently. Every fresh command creates a new run and supersedes active API work for that target; unsuccessful predecessors are linked. An Idempotency-Key replay returns its original identity and never redispatches. Inactive agreements preserve relationships. Financial validity is not a matching gate.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Idempotent receipt replay.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "202": { "description": "Durably admitted and execution acceptance confirmed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Conflicting idempotency key or unavailable target.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Conflicting idempotency key or unavailable target.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Execution acceptance is unconfirmed. Follow Location to inspect the retained workflow run.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Execution acceptance is unconfirmed. Follow Location to inspect the retained workflow run.", "request_id": "req_example" } } } } } } } }, "/v1/me/profile": { "get": { "tags": ["Identity"], "operationId": "getMyProfile", "summary": "Get your profile", "parameters": [], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "session", "responses": { "200": { "description": "Global account profile. Email verification is read-only.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "tags": ["Identity"], "operationId": "updateMyProfile", "summary": "Update your profile", "description": "Updates first and last names. Manage email addresses, verification and primary email selection through Clerk.", "parameters": [], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Current profile after reconciliation.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "The resource changed or the provider could only partially apply the update. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The resource changed or the provider could only partially apply the update. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/me/api-keys": { "get": { "tags": ["Identity"], "operationId": "listMyApiKeys", "summary": "List your API keys", "description": "Includes active, suspended and revoked metadata; never returns tokens. Ordered newest first, then ID.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "session", "responses": { "200": { "description": "Keys owned by the current account.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalApiKey" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "tags": ["Identity"], "operationId": "createMyApiKey", "summary": "Create an API key", "description": "Requires recent authentication. Returns the plaintext token once. A person may have at most 10 active keys.", "parameters": [], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "level": { "type": "string", "enum": ["read", "write", "admin"], "default": "read" }, "access": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["all"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["selected"] }, "organization_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "minItems": 1, "maxItems": 100 } }, "required": ["mode", "organization_ids"], "additionalProperties": false } ], "default": { "mode": "all" } } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created key, including its one-time token.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedPersonalApiKey" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "The resource changed or the provider could only partially apply the update. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The resource changed or the provider could only partially apply the update. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/me/api-keys/{id}": { "get": { "tags": ["Identity"], "operationId": "getMyApiKey", "summary": "Get an API key", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "session", "responses": { "200": { "description": "Safe key metadata.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalApiKey" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "tags": ["Identity"], "operationId": "updateMyApiKey", "summary": "Update an API key", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "level": { "type": "string", "enum": ["read", "write", "admin"] }, "access": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["all"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["selected"] }, "organization_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "minItems": 1, "maxItems": 100 } }, "required": ["mode", "organization_ids"], "additionalProperties": false } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated active key. Migrated keys retain their original organization restriction.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalApiKey" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The resource changed or the provider could only partially apply the update. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The resource changed or the provider could only partially apply the update. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "tags": ["Identity"], "operationId": "revokeMyApiKey", "summary": "Revoke an API key", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "session", "responses": { "204": { "description": "Key revoked. Repeating revocation succeeds; metadata is retained." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/me": { "get": { "operationId": "getMe", "summary": "Get the current principal", "tags": ["Identity"], "description": "Global identity without an active organization. Obtain organization access from organization discovery and detail.", "parameters": [], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "identity", "responses": { "200": { "description": "Authenticated identity.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "tags": ["Identity"], "operationId": "deleteMyAccount", "summary": "Delete your account", "parameters": [], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "session", "responses": { "204": { "description": "Global account deleted and personal access revoked. Organizations and retained business records are preserved." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/usage": { "get": { "operationId": "listUsage", "summary": "List usage by billing period", "tags": ["Usage"], "description": "Defaults to the current billing month. Supply both period bounds for up to 12 months, newest first. Before billing starts returns an empty page. current_capacity is always included, independent of billing activation and the requested period range. Historical period capacity is null; current capacity is an advisory snapshot, not a reservation.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "required": false, "name": "period_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "required": false, "name": "period_to", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Monthly consumption with historical policy terms.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsagePeriod" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] }, "current_capacity": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "remaining": { "type": ["integer", "null"] }, "reason": { "type": "string", "enum": ["available", "limit_reached"] }, "reserved": { "type": "integer" }, "as_of": { "type": "string", "format": "date-time" }, "period": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "period_end": { "type": "string", "format": "date-time" }, "counted": { "type": "integer" }, "policy_revision_id": { "type": ["string", "null"], "format": "uuid" } }, "required": [ "eligible", "remaining", "reason", "reserved", "as_of", "period", "period_end", "counted", "policy_revision_id" ] } }, "required": ["data", "next_cursor", "current_capacity"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/usage/policy": { "get": { "operationId": "getUsagePolicy", "summary": "Get usage policy", "tags": ["Usage"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current policy, revision preconditions and active upcoming policy changes. No policy is distinct from a zero allowance.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsagePolicy" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateUsagePolicy", "summary": "Update usage overage policy", "tags": ["Usage"], "description": "Changes current overage only. Requires the displayed month/revision and confirmation when increasing billable capacity. Cannot change quota, pricing or historical terms.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_current_month": { "type": "string", "pattern": "^(?:[1-9]\\d{3})-(?:0[1-9]|1[0-2])$" }, "expected_governing_revision_id": { "type": "string", "format": "uuid" }, "overage": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["disallowed"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["capped"] }, "quantity": { "type": "integer", "minimum": 0, "maximum": 10000000, "exclusiveMinimum": 0 } }, "required": ["mode", "quantity"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["uncapped"] } }, "required": ["mode"], "additionalProperties": false } ] }, "confirmed_billing_impact": { "type": "boolean" } }, "required": [ "expected_current_month", "expected_governing_revision_id", "overage", "confirmed_billing_impact" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Current policy after the update.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsagePolicy" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "The billing month or governing revision changed, or no policy is configured.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The billing month or governing revision changed, or no policy is configured.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/usage/policy/revisions": { "get": { "operationId": "listUsagePolicyRevisions", "summary": "List usage policy revisions", "tags": ["Usage"], "description": "Immutable policy history, newest first then ID. Includes cancellation and supersession; staff identity is redacted.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Policy revision history.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsagePolicyRevision" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/organizations": { "post": { "tags": ["Organizations"], "operationId": "createOrganization", "summary": "Create an organization", "description": "Creates a Clerk organization with initial membership and billing defaults. This operation is not idempotent. After an uncertain response, list your organizations before creating another.", "parameters": [], "security": [{ "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Usable organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "get": { "operationId": "listOrganizations", "summary": "List your organizations", "tags": ["Organizations"], "description": "Discover organizations before selecting one. Requires a valid personal API key or Clerk session, without X-Organization-Id or an active organization. A supplied organization header is ignored. Returns synchronized supported-role memberships, restricted by selected-key access and the original organization ceiling of migrated keys. No memberships returns an empty page. This discovery does not enforce organization MFA or grant resource access: subsequent requests enforce their normal organization, role, key, and MFA checks. Sessions must select an active organization before using its resources. Ordered by name, then opaque organization ID; cursors bind to the credential and its organization selection.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "identity", "responses": { "200": { "description": "Organization memberships permitted by this credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationSummary" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/organizations/{organization_id}": { "delete": { "tags": ["Organizations"], "operationId": "deleteOrganization", "summary": "Delete an organization", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "organization_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Organization deleted and billing finalized. Files are staged for retained cleanup; vector cleanup is best-effort." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "get": { "tags": ["Organizations"], "operationId": "getOrganization", "summary": "Get an organization", "description": "Synchronized business identity, local member count, nested settings, caller access and permission-derived capabilities. Reads do not contact Clerk. Slug and logo_url may be null until identity is synchronized. Missing settings are projected without inserts.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "organization_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Organization detail.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "tags": ["Organizations"], "operationId": "updateOrganization", "summary": "Update an organization", "description": "Partial update of business identity and nested settings. Omitted flags remain unchanged. Currency changes admit a durable workflow; re-saving the currency retries a failed conversion. Provider and database writes cannot be atomic: re-read after a partial failure.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "organization_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "settings": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "timezone": { "type": "string" }, "language": { "type": "string", "enum": ["en", "nb"] }, "require_mfa": { "type": "boolean" }, "agreement_defaults": { "type": "object", "properties": { "alerts": { "type": "object", "properties": { "flag_undercharges": { "type": "boolean" }, "flag_uncovered_items": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Saved settings and conversion workflow reference.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/organizations/{organization_id}/logo": { "put": { "tags": ["Organizations"], "operationId": "setOrganizationLogo", "summary": "Set the organization logo", "description": "Upload a PNG or JPEG. The complete multipart body must fit the API 2 MiB limit.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "organization_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": ["file"] } } } }, "responses": { "200": { "description": "Organization with the updated logo.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/members": { "get": { "tags": ["Members"], "operationId": "listOrganizationMembers", "summary": "List organization members", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Members ordered by opaque user ID. Missing identity fields remain null.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMember" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/members/{user_id}": { "get": { "tags": ["Members"], "operationId": "getOrganizationMember", "summary": "Get an organization member", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "user_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Membership detail.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMember" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "tags": ["Members"], "operationId": "updateOrganizationMember", "summary": "Update a member role", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "user_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["admin", "member"] } }, "required": ["role"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated membership. Last administrator protection applies.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMember" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "tags": ["Members"], "operationId": "removeOrganizationMember", "summary": "Remove an organization member", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "user_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Membership removed; global account retained. Last administrator protection applies." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/me/organizations/{organization_id}": { "delete": { "tags": ["Identity"], "operationId": "leaveOrganization", "summary": "Leave an organization", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "organization_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Your membership was removed. Global account retained; last administrator protection applies." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invitations": { "get": { "tags": ["Invitations"], "operationId": "listOrganizationInvitations", "summary": "List organization invitations", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": ["pending", "accepted", "revoked", "expired"] }, "required": false, "name": "status", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Invitations in provider order with an opaque, filter-bound offset continuation. Concurrent changes may cause skipped or repeated entries.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationInvitation" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "tags": ["Invitations"], "operationId": "createOrganizationInvitation", "summary": "Invite an organization member", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["admin", "member"] } }, "required": ["email", "role"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Invitation sent. Acceptance remains with Clerk. Do not automatically retry uncertain sends; inspect invitations first.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvitation" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invitations/{id}": { "get": { "tags": ["Invitations"], "operationId": "getOrganizationInvitation", "summary": "Get an organization invitation", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Invitation detail.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvitation" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "tags": ["Invitations"], "operationId": "revokeOrganizationInvitation", "summary": "Revoke an organization invitation", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "admin", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Invitation revoked. Already-revoked invitations succeed; accepted invitations conflict." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The operation conflicts with the current organization state. Refresh before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The operation conflicts with the current organization state. Refresh before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/check": { "post": { "operationId": "checkInvoice", "summary": "Check an invoice against agreements", "description": "Evaluates a completed invoice against its eligible matched agreements. A pair is not eligible while a claim that is not cancelled holds one of its alerts that is not dismissed; a published check replaces all of the pair's alerts. The selected agreements and the assessed invoice and agreement inputs are captured once at admission. If those inputs change before a pair finishes, that item fails with stale_input and no result is published; submit a new check. A successful evaluation with no findings completes normally and differs from a failed item. Completed evaluations are immutable ComplianceCheck resources. Cancel through the workflow run. This command does not run matching.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20, "description": "Omit to check every currently eligible matched agreement." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Replay of an Idempotency-Key. The original workflow run is returned.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "202": { "description": "Check admitted. One workflow run groups the request and one item evaluates each invoice and agreement pair. A completed item result references its ComplianceCheck.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "no_eligible_agreements: no selected agreement is eligible, or a supplied agreement is not (for example, a claim holds the pair); nothing was started or billed. check_in_progress: a selected pair already has unfinished work; workflow_run_id is included when this API owns it. conflict: more agreements are eligible than one check takes and agreement_ids was omitted, the Idempotency-Key was used with a different request, the named run or items cannot be retried, or the admitted run ended concurrently.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_no_eligible_agreements_check_in_progress_conflict" }, "example": { "error": { "code": "no_eligible_agreements", "message": "no_eligible_agreements: no selected agreement is eligible, or a supplied agreement is not (for example, a claim holds the pair); nothing was started or billed. check_in_progress: a selected pair already has unfinished work; workflow_run_id is included when this API owns it. conflict: more agreements are eligible than one check takes and agreement_ids was omitted, the Idempotency-Key was used with a different request, the named run or items cannot be retried, or the admitted run ended concurrently.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Dispatch was not confirmed. Inspect workflow_run_id before retrying. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": false, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Dispatch was not confirmed. Inspect workflow_run_id before retrying. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/check/retry": { "post": { "operationId": "retryInvoiceCheck", "summary": "Retry failed invoice check items", "description": "Creates a new workflow run linked to an unsuccessful check of this invoice. Only its failed or cancelled items are retried, all of them or the named subset. Eligibility is verified again and current inputs are captured. Completed items are never rerun by retry; submit a new check to reevaluate them.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" }, "item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20, "description": "Omit to retry every failed or cancelled item of the run." } }, "required": ["workflow_run_id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Replay of an Idempotency-Key. The original workflow run is returned.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "202": { "description": "Check admitted. One workflow run groups the request and one item evaluates each invoice and agreement pair. A completed item result references its ComplianceCheck.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "no_eligible_agreements: no selected agreement is eligible, or a supplied agreement is not (for example, a claim holds the pair); nothing was started or billed. check_in_progress: a selected pair already has unfinished work; workflow_run_id is included when this API owns it. conflict: more agreements are eligible than one check takes and agreement_ids was omitted, the Idempotency-Key was used with a different request, the named run or items cannot be retried, or the admitted run ended concurrently.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_no_eligible_agreements_check_in_progress_conflict" }, "example": { "error": { "code": "no_eligible_agreements", "message": "no_eligible_agreements: no selected agreement is eligible, or a supplied agreement is not (for example, a claim holds the pair); nothing was started or billed. check_in_progress: a selected pair already has unfinished work; workflow_run_id is included when this API owns it. conflict: more agreements are eligible than one check takes and agreement_ids was omitted, the Idempotency-Key was used with a different request, the named run or items cannot be retried, or the admitted run ended concurrently.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Dispatch was not confirmed. Inspect workflow_run_id before retrying. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": false, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Dispatch was not confirmed. Inspect workflow_run_id before retrying. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/check": { "post": { "operationId": "checkAgreements", "summary": "Check every agreement for unchecked invoices", "description": "Starts one agreement check, as `POST /v1/agreements/{id}/check` would, for every active and ready agreement that has unchecked invoices. Agreements that are not ready are skipped. One request admits at most 5000 invoices in total, filled agreement by agreement in ID order, newest invoices first; has_more reports that more remain, so repeat the request once these runs finish. Every admitted run is returned: follow each one. A run whose dispatch failed fails, its items with dispatch_failed; one whose acceptance was not confirmed either starts or, if it has not started five minutes after admission, fails with admission_expired items; its invoices are unchecked again either way.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "No agreement has unchecked invoices; nothing was started.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementsCheckAccepted" } } } }, "202": { "description": "One workflow run per admitted agreement.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementsCheckAccepted" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/check": { "post": { "operationId": "checkAgreement", "summary": "Check an agreement's unchecked invoices", "description": "Checks the agreement against its matched invoices that have no current result: never checked, or whose last check failed or was cancelled. This is the set `GET /v1/invoices?agreement_ids={id}&alert_scope=selected_agreements&alert_checked=false&alert_checkable=true` lists, apart from invoices already being checked, invoices without a primary document, and pairs a claim holds (a claim that is not cancelled holds one of the pair's alerts that is not dismissed). Completed checks are kept, including outdated ones; check the invoice, recheck a topic or reset the agreement to evaluate them again, unless a claim holds the pair. invoice_ids limits the check to up to 20 of those invoices. One request admits at most 5000 invoices, newest first; has_more reports that more remain. Each pair reads its invoice and agreement when it starts, and publishes like an invoice check: it replaces all of the pair's alerts. Cancel through the workflow run.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20, "description": "A sample: check only these of the unchecked invoices. Omit to check all of them." } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Check admitted. One item evaluates each invoice with this agreement.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementCheckAccepted" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "agreement_not_checkable: the agreement is not active or not ready. nothing_to_check: no selected invoice is unchecked and eligible; nothing was started. conflict: the admitted run ended before its execution was recorded.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_agreement_not_checkable_nothing_to_check_conflict" }, "example": { "error": { "code": "agreement_not_checkable", "message": "agreement_not_checkable: the agreement is not active or not ready. nothing_to_check: no selected invoice is unchecked and eligible; nothing was started. conflict: the admitted run ended before its execution was recorded.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Dispatch was not confirmed. Inspect workflow_run_id before retrying. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": false, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Dispatch was not confirmed. Inspect workflow_run_id before retrying. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topics/{id}/recheck": { "post": { "operationId": "recheckAlertTopic", "summary": "Recheck a topic's invoices", "description": "Checks the agreement again against every invoice behind the topic's alerts, completed checks included, as one agreement check. Each pair publishes like an invoice check: it replaces all of the pair's alerts, including those in other topics and dismissed or credited ones, which come back as new pending alerts if the check finds them again. Pairs a claim holds (a claim that is not cancelled holds one of the pair's alerts that is not dismissed), pairs already being checked and invoices that cannot be checked against the agreement are left as they are and counted in skipped_count. A pair whose check fails keeps its alerts and counts as unchecked, so the next agreement check retries it. The topic's agreement must be active and ready. A recheck is not idempotent: once its run finishes, the same request starts a new one. Topics are reconciled after the run.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "202": { "description": "Recheck admitted. One item evaluates each of the topic's checkable invoices.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicRecheckAccepted" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "agreement_not_checkable: the topic's agreement is not active or not ready. nothing_to_check: none of the topic's invoices can be rechecked now; nothing was started. conflict: the topic covers more than 5000 invoices, or the admitted run ended before its execution was recorded.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_agreement_not_checkable_nothing_to_check_conflict" }, "example": { "error": { "code": "agreement_not_checkable", "message": "agreement_not_checkable: the topic's agreement is not active or not ready. nothing_to_check: none of the topic's invoices can be rechecked now; nothing was started. conflict: the topic covers more than 5000 invoices, or the admitted run ended before its execution was recorded.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Dispatch was not confirmed. Inspect workflow_run_id before retrying. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": false, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Dispatch was not confirmed. Inspect workflow_run_id before retrying. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/check/reset": { "post": { "operationId": "resetInvoiceCheck", "summary": "Reset an invoice's checks and alerts", "description": "Starts the invoice's evaluation over: cancels its unfinished checks, deletes the alerts of its invoice and agreement pairs and marks those pairs unchecked so an agreement check picks them up again. A pair a claim holds (a claim that is not cancelled holds one of its alerts that is not dismissed) keeps its alerts and its result. Completed ComplianceChecks and their findings are retained. One transaction. Topics emptied by the deletion are removed by the agreement's next topic reconciliation, which this requests.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "What the reset changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckReset" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/check/reset": { "post": { "operationId": "resetAgreementCheck", "summary": "Reset an agreement's checks and alerts", "description": "Starts the agreement's evaluation over: cancels its unfinished checks, deletes the alerts of its invoice and agreement pairs and marks those pairs unchecked so an agreement check picks them up again. A pair a claim holds (a claim that is not cancelled holds one of its alerts that is not dismissed) keeps its alerts and its result. Completed ComplianceChecks and their findings are retained. One transaction. Topics emptied by the deletion are removed by the agreement's next topic reconciliation, which this requests.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "What the reset changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckReset" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/alert-topics/reconcile": { "post": { "operationId": "reconcileAgreementAlertTopics", "summary": "Reconcile an agreement's alert topics", "tags": ["Alerts"], "description": "Groups the agreement's alerts into topics: new alerts join existing or new topics, and topics left without alerts are removed. Locked topics keep their alerts. Compliance checks request this automatically after they publish. One reconciliation runs per agreement at a time, and it reads every alert of the agreement before it completes, so a request while one is queued or running returns that run instead of starting another.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A reconciliation is already queued or running; it covers this request.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "202": { "description": "Reconciliation admitted and execution acceptance confirmed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The admitted run ended before its execution was recorded. Submit a new request.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The admitted run ended before its execution was recorded. Submit a new request.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "The run could not be started, or its acceptance is unconfirmed. Follow Location to inspect the workflow run before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "The run could not be started, or its acceptance is unconfirmed. Follow Location to inspect the workflow run before retrying.", "request_id": "req_example" } } } } } } } }, "/v1/compliance-checks": { "get": { "operationId": "listComplianceChecks", "summary": "List compliance checks", "description": "Completed evaluations, newest first, including successful checks with no findings. Running, failed and cancelled work is observed through workflow runs and never appears here. Results are immutable; freshness is derived on read.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "invoice_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "agreement_id", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Completed on or after this calendar date in the organization's timezone." }, "required": false, "description": "Completed on or after this calendar date in the organization's timezone.", "name": "completed_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Completed on or before this calendar date in the organization's timezone." }, "required": false, "description": "Completed on or before this calendar date in the organization's timezone.", "name": "completed_through", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A bounded page of completed checks.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceCheck" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/compliance-checks/{id}": { "get": { "operationId": "getComplianceCheck", "summary": "Get a compliance check", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The completed check.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceCheck" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/compliance-checks/{id}/findings": { "get": { "operationId": "listComplianceCheckFindings", "summary": "List compliance check findings", "description": "Findings as assessed, in their original order. Each carries the invoice line values, expected values, cited excerpts and referenced price item values captured at publication, so it stays interpretable after invoice edits, price deletion, reprocessing or document unlinking. Editing or dismissing the resulting alert never changes a finding.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A bounded page of findings.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceCheckFinding" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/compliance-checks/{id}/transcript": { "get": { "operationId": "getComplianceCheckTranscript", "summary": "Get a compliance check transcript", "description": "How the check reached its result: the display form of each tool call, in order, followed by the final summary when it fits the transcript size limit. Prompts, reasoning and intermediate model messages are not retained. An alert links its check through provenance.retained_check.", "tags": ["Compliance checks"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The retained transcript.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceCheckTranscript" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/activity": { "get": { "operationId": "listActivity", "summary": "Read an entity activity timeline", "tags": ["Activity"], "description": "Returns individual events and top-level comments, newest first. Supports invoices, agreements, individual alerts, claims, and topics (events only). Related-alert inclusion is explicit and adds events only. Alert filters match direct identities and recorded alert references before pagination; they return events only. Cursors retain timestamp precision and bind to the organization, entity and filters. Optional group_changes returns grouping metadata for this page only, using a rolling five-minute window. Comments break groups. value_blind_actions ignores change values for selected actions on the same entity. Pagination always counts entries, including when groups span pages. This is a live feed, not a snapshot or version-history API.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "agreement", "invoice", "alert", "claim", "topic", "invoice_import", "document" ] }, "required": true, "name": "entity_type", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "entity_id", "in": "query" }, { "schema": { "type": "string", "enum": ["activity", "comment"] }, "required": false, "name": "entry_type", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": "false" }, "required": false, "name": "include_related_alerts", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": "false", "description": "Include page-local grouping metadata. Pagination still counts entries, not groups." }, "required": false, "description": "Include page-local grouping metadata. Pagination still counts entries, not groups.", "name": "group_changes", "in": "query" }, { "schema": { "type": "string", "description": "Actions grouped by changed field names rather than values. Requires group_changes=true; at most 50 actions." }, "required": false, "description": "Actions grouped by changed field names rather than values. Requires group_changes=true; at most 50 actions.", "name": "value_blind_actions", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Override automatic suppression of redundant alert summaries. Omit to suppress only when related alerts contribute events." }, "required": false, "description": "Override automatic suppression of redundant alert summaries. Omit to suppress only when related alerts contribute events.", "name": "suppress_alert_scope_rollups", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "alert_id", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is" }, "required": false, "name": "alert_operator", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of timeline entries and an opaque next cursor.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEntry" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Grouping signature. Adjacent fragments with this key may join only within the rolling five-minute window, without an intervening comment." }, "event_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 }, "first_occurred_at": { "type": "string", "format": "date-time" }, "last_occurred_at": { "type": "string", "format": "date-time" } }, "required": ["key", "event_ids", "first_occurred_at", "last_occurred_at"] }, "maxItems": 100 } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/comments": { "post": { "operationId": "createComment", "summary": "Create a comment or reply", "tags": ["Comments"], "description": "Supports invoices, agreements, individual alerts and claims. Bodies are trimmed and limited to 1–5,000 characters. The authenticated user owns the comment, including API-key requests. Replies must reference a top-level comment on the same resource. Creation is non-idempotent. Do not automatically retry an uncertain response. Inspect the timeline for a root comment, or the parent comment’s replies for a reply.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": ["invoice", "agreement", "alert", "claim"] }, "entity_id": { "type": "string", "format": "uuid" }, "parent_comment_id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": ["entity_type", "entity_id", "body"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created comment.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/comments/{id}": { "get": { "operationId": "getComment", "summary": "Get a comment", "tags": ["Comments"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The comment, owning entity, author and reply count.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateComment", "summary": "Edit your comment", "tags": ["Comments"], "description": "Only the author may edit, including when using an admin credential. Changes the body only, using last-write-wins semantics. Identical edits preserve timestamps; edits never move a comment in the timeline.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": ["body"], "additionalProperties": false } } } }, "responses": { "200": { "description": "The comment, owning entity, author and reply count.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteComment", "summary": "Delete your comment", "tags": ["Comments"], "description": "Only the author may delete. Permanently deleting a top-level comment also deletes its replies, including replies by other authors. Repeated deletion and non-owned comments return 404.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Comment and any replies deleted." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/comments/{id}/replies": { "get": { "operationId": "listCommentReplies", "summary": "List comment replies", "tags": ["Comments"], "description": "Replies to a top-level comment, ordered by occurrence time and ID oldest first. Cursors are bound to the organization and parent comment.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of replies.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/refunds": { "get": { "operationId": "listClaimRefunds", "summary": "List claim refunds", "tags": ["Claims"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Refunds ordered by creation time and ID descending.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimRefund" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createClaimRefund", "summary": "Record a claim refund", "tags": ["Claims"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "maxLength": 100, "pattern": "^\\d+(?:\\.\\d+)?$" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "comment": { "type": ["string", "null"], "maxLength": 2000 }, "credit_note_id": { "type": ["string", "null"], "format": "uuid" } }, "required": ["amount", "currency_code"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created refund. Creation is non-idempotent.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "ETag": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRefund" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The refund or credit-note relationship conflicts with the current state.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The refund or credit-note relationship conflicts with the current state.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/refunds/{refund_id}": { "get": { "operationId": "getClaimRefund", "summary": "Get a claim refund", "tags": ["Claims"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "refund_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current refund.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRefund" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateClaimRefund", "summary": "Update a claim refund", "tags": ["Claims"], "description": "Omitted fields are unchanged. Null comment or credit_note_id clears it. Optional If-Match prevents stale edits. A credit-note link does not change the amount or currency.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "refund_id", "in": "path" }, { "schema": { "type": "string", "maxLength": 4096 }, "required": false, "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "maxLength": 100, "pattern": "^\\d+(?:\\.\\d+)?$" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "comment": { "type": ["string", "null"], "maxLength": 2000 }, "credit_note_id": { "type": ["string", "null"], "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Current refund.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRefund" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The refund or credit-note relationship conflicts with the current state.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The refund or credit-note relationship conflicts with the current state.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed. Fetch it again before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed. Fetch it again before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteClaimRefund", "summary": "Delete a claim refund", "tags": ["Claims"], "description": "Preserves the credit-note attachment. Repeated deletion returns 404.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "refund_id", "in": "path" }, { "schema": { "type": "string", "maxLength": 4096 }, "required": false, "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Refund deleted." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed. Fetch it again before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed. Fetch it again before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/export": { "get": { "operationId": "exportClaim", "summary": "Export a claim", "tags": ["Claims"], "description": "Generates and returns the requested file in this response. CSV contains alert rows; XLSX adds a refund-summary sheet; PDF summarizes topics with stored descriptions and key questions, up to two invoice examples per topic, and selected sources (up to two per topic/example). PDF counts and totals cover the full selection; CSV/XLSX contain all alert rows. Refund totals remain separate. Claimed findings are always included. include_pending adds pending members to the same outstanding bucket; include_credited adds findings the supplier has already credited as a separate bucket, and the PDF then states the total with the outstanding and credited parts beneath it. Dismissed and removed alerts are never exported. Reads one consistent snapshot. CSV/XLSX decimal amounts remain exact in original currencies; PDF amounts round half up to currency-specific decimal places after aggregation. Null impact contributes zero. Export headings are English; source text retains its language. Repeating this read generates a fresh export. No workflow, polling, or saved export is created.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": ["csv", "xlsx", "pdf"] }, "required": true, "name": "format", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": "false", "description": "Also include pending members, reported together with claimed findings as one outstanding bucket. Default false." }, "required": false, "description": "Also include pending members, reported together with claimed findings as one outstanding bucket. Default false.", "name": "include_pending", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": "false", "description": "Also include findings the supplier has already credited, reported as a separate bucket. Default false." }, "required": false, "description": "Also include findings the supplier has already credited, reported as a separate bucket. Default false.", "name": "include_credited", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The generated file, with a download filename. Content type follows format.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "required": true }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": true } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/credit-notes": { "get": { "operationId": "listClaimCreditNotes", "summary": "List claim credit notes", "tags": ["Claims"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Distinct credit notes ordered by invoice creation time and ID descending.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimCreditNote" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "attachClaimCreditNote", "summary": "Attach a claim credit note", "tags": ["Claims"], "description": "Optionally creates a refund from the absolute net note amount in its own currency. A duplicate attachment returns 409. Attachment alone does not record recovery.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credit_note_id": { "type": "string", "format": "uuid" }, "create_refund": { "type": "boolean", "default": false } }, "required": ["credit_note_id"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Attached credit note.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "ETag": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimCreditNote" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The refund or credit-note relationship conflicts with the current state.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The refund or credit-note relationship conflicts with the current state.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/credit-notes/{credit_note_id}": { "get": { "operationId": "getClaimCreditNote", "summary": "Get a claim credit note", "tags": ["Claims"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "credit_note_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Credit note with direct attachment and invoice-derived evidence.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimCreditNote" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/credit-notes/{credit_note_id}/remove": { "post": { "operationId": "removeClaimCreditNote", "summary": "Remove a claim credit-note attachment", "tags": ["Claims"], "description": "Keeps invoice matches. Explicitly keep the linked refund or delete only an attachment-generated refund. delete_generated requires the current strong ETag from the individual GET.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "credit_note_id", "in": "path" }, { "schema": { "type": "string", "maxLength": 4096 }, "required": false, "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refund_outcome": { "type": "string", "enum": ["keep", "delete_generated"] } }, "required": ["refund_outcome"], "additionalProperties": false } } } }, "responses": { "204": { "description": "Direct attachment removed." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The refund or credit-note relationship conflicts with the current state.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The refund or credit-note relationship conflicts with the current state.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed. Fetch it again before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed. Fetch it again before retrying.", "request_id": "req_example" } } } } }, "428": { "description": "A current strong If-Match is required to delete a generated refund.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_required" }, "example": { "error": { "code": "precondition_required", "message": "A current strong If-Match is required to delete a generated refund.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/documents": { "get": { "operationId": "listClaimDocuments", "summary": "List claim invoice documents", "tags": ["Claims"], "description": "Source documents of the completed, nondeleted invoices whose alerts are currently attached to the claim, one item per invoice, ordered by invoice number (missing numbers last) and ID. Invoices without documents are omitted. Read a credit note's documents with GET /v1/invoices/{id}/documents; list the claim's credit notes with GET /v1/claims/{id}/credit-notes.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of invoices with their documents; next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimInvoiceDocuments" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims": { "get": { "operationId": "listClaims", "summary": "List claims", "tags": ["Claims"], "description": "All claim statuses are included by default. Filters combine with AND, values within a filter with OR. Dates are inclusive calendar dates in the organization timezone. Search matches claim titles or supplier names. Suppliers come from the agreement, falling back to current alerts for legacy agreements without suppliers. Sort by created_at or updated_at with asc/desc direction; the default is created_at descending, with ID as the tie-breaker. Amounts are exact strings grouped by original currency; removed alerts do not contribute to amounts.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "statuses", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "creator_user_ids", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Literal substring of the claim title or supplier name." }, "required": false, "description": "Literal substring of the claim title or supplier name.", "name": "search", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "created_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "created_through", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": ["created_at", "updated_at"], "default": "created_at" }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "required": false, "name": "direction", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of claims.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createClaim", "summary": "Create a claim", "tags": ["Claims"], "description": "Creates a pending claim in an owned, nondeleted active or archived agreement. Titles need not be unique. Optionally send alerts to add alerts in the same transaction, using the rules of POST /v1/claims/{id}/alerts: alerts.alert_ids or alerts.filter, at most 5000 alerts. If the request fails, no claim is created. Creation is non-idempotent: retrying can create another claim. No Idempotency-Key is supported; inspect the list after an uncertain response before creating again.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "alerts": { "type": "object", "properties": { "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Explicit alerts. The command applies to every listed alert or fails: an unknown ID returns 404 and an alert that may not be changed returns 409." }, "filter": { "type": "object", "properties": { "mine": { "type": "boolean", "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "team_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "claim_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "has_claim": { "type": "boolean", "description": "Use false to select alerts that are not currently attached to any claim." }, "claim_statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "minItems": 1, "maxItems": 50, "description": "Match alerts whose current claim has any of these statuses." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on any of these invoices." }, "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these agreements." }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these suppliers." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "topic_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "excluded_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "has_topic": { "type": "boolean", "description": "Use false to select uncategorized alerts." }, "statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "minItems": 1, "maxItems": 50 }, "confidence_levels": { "type": "array", "items": { "type": "string", "enum": ["high", "mid", "low", "null"] }, "minItems": 1, "maxItems": 50, "description": "Match any listed confidence level; null matches alerts without one." }, "currency_codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 1, "maxItems": 50 }, "correction_types": { "type": "array", "items": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "minItems": 1, "maxItems": 50 }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "impact_min": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "impact_max": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "issued_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "issued_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "created_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "created_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." } }, "additionalProperties": false, "description": "Every alert matching this filter when the claim is created. Takes the GET /v1/alerts filters with JSON lists and booleans. Matching alerts that may not be added are left out; read the created claim for its counts." }, "excluded_alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Alerts to leave out of a filter selection. Only valid with filter." } }, "additionalProperties": false, "description": "Alerts to add in the same transaction, with the rules of POST /v1/claims/{id}/alerts. With alert_ids, an alert that does not qualify fails the request and no claim is created." } }, "required": ["agreement_id", "title"], "additionalProperties": false } } } }, "responses": { "201": { "description": "The created claim with its current counts and amounts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The agreement, an alert in alerts.alert_ids within that agreement, or a selected team was not found. No claim was created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The agreement, an alert in alerts.alert_ids within that agreement, or a selected team was not found. No claim was created.", "request_id": "req_example" } } } } }, "409": { "description": "The agreement is deleted or not active or archived, an alert in alerts.alert_ids does not qualify, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. No claim was created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The agreement is deleted or not active or archived, an alert in alerts.alert_ids does not qualify, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. No claim was created.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/metrics": { "get": { "operationId": "getClaimMetrics", "summary": "Get claim totals", "tags": ["Claims"], "description": "Uses exactly the claim-list filters. Empty claims count. Alert counts distinguish total, pending, claimed, credited, and dismissed attached alerts. Alert impact includes all attached alerts regardless of claim status or invoice eligibility; it does not represent refunded or recovered money.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "statuses", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "creator_user_ids", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Literal substring of the claim title or supplier name." }, "required": false, "description": "Literal substring of the claim title or supplier name.", "name": "search", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "created_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "created_through", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Claim counts and amounts per currency.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimMetrics" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}": { "get": { "operationId": "getClaim", "summary": "Get a claim", "tags": ["Claims"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The canonical claim with current counts and amounts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateClaim", "summary": "Edit a claim title", "tags": ["Claims"], "description": "Only title is editable. Null clears the title; omission and an unchanged title are no-ops. Agreement and status cannot be edited here. Commands serialize with other claim writes; no client revision is required.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The canonical claim with current counts and amounts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The claim is locked, the selected membership changed, or the operation is incompatible.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The claim is locked, the selected membership changed, or the operation is incompatible.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/transition": { "post": { "operationId": "transitionClaim", "summary": "Change claim status", "tags": ["Claims"], "description": "Repeating the current status is a no-op. All transitions are supported except completed to cancelled: reopen to pending or in_progress first. Cancellation dismisses attached pending and claimed alerts with category other and note Claim cancelled; credited members keep their status. Memberships and previous dismissal feedback are preserved. That note records the cancellation, not feedback about the agreement, so no dismissal-context suggestion starts. Reopening changes claim status only; it does not reset alert dispositions or restore released memberships.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] } }, "required": ["status"], "additionalProperties": false } } } }, "responses": { "200": { "description": "The canonical claim with current counts and amounts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The claim is locked, the selected membership changed, or the operation is incompatible.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The claim is locked, the selected membership changed, or the operation is incompatible.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/delete": { "post": { "operationId": "deleteClaim", "summary": "Delete a claim", "tags": ["Claims"], "description": "Permanently deletes the claim, comments, memberships, refund records and credit-note links, including for completed claims. Explicitly choose the attached alerts' outcome: pending returns claimed alerts to pending, dismissed dismisses pending and claimed alerts. Credited alerts keep their status either way. Alerts, dismissal snapshots and domain activity survive. Existing dismissal feedback is preserved. A dismissal with a category or note starts one agreement_context_suggestions workflow run per agreement, which may propose edits to that agreement's instructions for review. The command does not wait for it. The claim subsequently returns 404; repeated deletion returns 404.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "alert_outcome": { "type": "string", "enum": ["pending"] } }, "required": ["alert_outcome"], "additionalProperties": false }, { "type": "object", "properties": { "alert_outcome": { "type": "string", "enum": ["dismissed"] }, "dismissal_feedback": { "type": "object", "properties": { "category": { "type": ["string", "null"], "enum": [ "wrong_alert", "valid_not_actioning", "already_handled", "duplicate_covered", "other", null ] }, "note": { "type": ["string", "null"], "maxLength": 2000 } }, "additionalProperties": false } }, "required": ["alert_outcome"], "additionalProperties": false } ] } } } }, "responses": { "204": { "description": "Claim deleted." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The claim is locked, the selected membership changed, or the operation is incompatible.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The claim is locked, the selected membership changed, or the operation is incompatible.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/alerts": { "post": { "operationId": "addClaimAlerts", "summary": "Add alerts to a claim", "tags": ["Claims"], "description": "Attaches the selected alerts. Only pending/in_progress claims accept alerts. Pending alerts become claimed; credited and dismissed alerts keep their status while attached. Alerts already in this claim are left alone, except that a member set back to pending is claimed again. With alert_ids, an alert outside the claim agreement returns 404, and membership in another claim or an invoice that is not completed returns 409; use transfer to move alerts between claims. A filter covers alerts in the claim agreement and skips those cases. Select alerts with alert_ids or with filter. The command is one transaction and changes at most 5000 alerts; a filter that would change more returns 409 and changes nothing. Matching alerts already in the requested state, or left alone, do not count toward the limit, so a retry is safe.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Explicit alerts. The command applies to every listed alert or fails: an unknown ID returns 404 and an alert that may not be changed returns 409." }, "filter": { "type": "object", "properties": { "mine": { "type": "boolean", "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "team_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "claim_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "has_claim": { "type": "boolean", "description": "Use false to select alerts that are not currently attached to any claim." }, "claim_statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "minItems": 1, "maxItems": 50, "description": "Match alerts whose current claim has any of these statuses." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on any of these invoices." }, "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these agreements." }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these suppliers." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "topic_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "excluded_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "has_topic": { "type": "boolean", "description": "Use false to select uncategorized alerts." }, "statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "minItems": 1, "maxItems": 50 }, "confidence_levels": { "type": "array", "items": { "type": "string", "enum": ["high", "mid", "low", "null"] }, "minItems": 1, "maxItems": 50, "description": "Match any listed confidence level; null matches alerts without one." }, "currency_codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 1, "maxItems": 50 }, "correction_types": { "type": "array", "items": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "minItems": 1, "maxItems": 50 }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "impact_min": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "impact_max": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "issued_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "issued_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "created_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "created_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." } }, "additionalProperties": false, "description": "Every alert matching this filter when the command runs. Takes the GET /v1/alerts filters with JSON lists and booleans. Matching alerts that may not be changed are left alone and counted in skipped_count." }, "excluded_alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Alerts to leave out of a filter selection. Only valid with filter." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "How many alerts the command changed and how many matching alerts were left alone. Read the claim for its current counts and amounts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSelectionResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The claim, a transfer target, an alert in alert_ids, or a selected team was not found.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The claim, a transfer target, an alert in alert_ids, or a selected team was not found.", "request_id": "req_example" } } } } }, "409": { "description": "The claim is locked or does not accept alerts, an alert in alert_ids does not qualify, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The claim is locked or does not accept alerts, an alert in alert_ids does not qualify, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/alerts/remove": { "post": { "operationId": "removeClaimAlerts", "summary": "Remove alerts from a claim", "tags": ["Claims"], "description": "Releases the selected current memberships. Claimed alerts return to pending; pending, credited, and dismissed alerts keep their status. Completed claims are locked. With alert_ids, an alert that is not a current member returns 409, so repeating a removal conflicts. A filter covers current members only, so repeating it changes nothing. Select alerts with alert_ids or with filter. The command is one transaction and changes at most 5000 alerts; a filter that would change more returns 409 and changes nothing. Matching alerts already in the requested state, or left alone, do not count toward the limit, so a retry is safe.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Explicit alerts. The command applies to every listed alert or fails: an unknown ID returns 404 and an alert that may not be changed returns 409." }, "filter": { "type": "object", "properties": { "mine": { "type": "boolean", "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "team_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "claim_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "has_claim": { "type": "boolean", "description": "Use false to select alerts that are not currently attached to any claim." }, "claim_statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "minItems": 1, "maxItems": 50, "description": "Match alerts whose current claim has any of these statuses." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on any of these invoices." }, "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these agreements." }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these suppliers." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "topic_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "excluded_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "has_topic": { "type": "boolean", "description": "Use false to select uncategorized alerts." }, "statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "minItems": 1, "maxItems": 50 }, "confidence_levels": { "type": "array", "items": { "type": "string", "enum": ["high", "mid", "low", "null"] }, "minItems": 1, "maxItems": 50, "description": "Match any listed confidence level; null matches alerts without one." }, "currency_codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 1, "maxItems": 50 }, "correction_types": { "type": "array", "items": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "minItems": 1, "maxItems": 50 }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "impact_min": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "impact_max": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "issued_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "issued_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "created_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "created_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." } }, "additionalProperties": false, "description": "Every alert matching this filter when the command runs. Takes the GET /v1/alerts filters with JSON lists and booleans. Matching alerts that may not be changed are left alone and counted in skipped_count." }, "excluded_alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Alerts to leave out of a filter selection. Only valid with filter." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "How many alerts the command changed and how many matching alerts were left alone. Read the claim for its current counts and amounts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSelectionResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The claim, a transfer target, an alert in alert_ids, or a selected team was not found.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The claim, a transfer target, an alert in alert_ids, or a selected team was not found.", "request_id": "req_example" } } } } }, "409": { "description": "The claim is locked or does not accept alerts, an alert in alert_ids does not qualify, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The claim is locked or does not accept alerts, an alert in alert_ids does not qualify, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/claims/{id}/alerts/transfer": { "post": { "operationId": "transferClaimAlerts", "summary": "Transfer claim alerts", "tags": ["Claims"], "description": "Moves the selected current members to a different pending/in_progress claim in the same agreement, recording release and reassignment together. Completed sources are locked; cancelled sources may transfer. Pending members become claimed; other statuses are kept. With alert_ids, an alert that is not a current member or whose invoice is not completed returns 409. A filter covers current members and skips alerts whose invoice is not completed. Select alerts with alert_ids or with filter. The command is one transaction and changes at most 5000 alerts; a filter that would change more returns 409 and changes nothing. Matching alerts already in the requested state, or left alone, do not count toward the limit, so a retry is safe.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Explicit alerts. The command applies to every listed alert or fails: an unknown ID returns 404 and an alert that may not be changed returns 409." }, "filter": { "type": "object", "properties": { "mine": { "type": "boolean", "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "team_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "claim_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "has_claim": { "type": "boolean", "description": "Use false to select alerts that are not currently attached to any claim." }, "claim_statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "minItems": 1, "maxItems": 50, "description": "Match alerts whose current claim has any of these statuses." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on any of these invoices." }, "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these agreements." }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these suppliers." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "topic_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "excluded_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "has_topic": { "type": "boolean", "description": "Use false to select uncategorized alerts." }, "statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "minItems": 1, "maxItems": 50 }, "confidence_levels": { "type": "array", "items": { "type": "string", "enum": ["high", "mid", "low", "null"] }, "minItems": 1, "maxItems": 50, "description": "Match any listed confidence level; null matches alerts without one." }, "currency_codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 1, "maxItems": 50 }, "correction_types": { "type": "array", "items": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "minItems": 1, "maxItems": 50 }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "impact_min": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "impact_max": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "issued_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "issued_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "created_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "created_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." } }, "additionalProperties": false, "description": "Every alert matching this filter when the command runs. Takes the GET /v1/alerts filters with JSON lists and booleans. Matching alerts that may not be changed are left alone and counted in skipped_count." }, "excluded_alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Alerts to leave out of a filter selection. Only valid with filter." }, "target_claim_id": { "type": "string", "format": "uuid" } }, "required": ["target_claim_id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "How many alerts the command changed and how many matching alerts were left alone. Read the claim for its current counts and amounts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSelectionResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The claim, a transfer target, an alert in alert_ids, or a selected team was not found.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The claim, a transfer target, an alert in alert_ids, or a selected team was not found.", "request_id": "req_example" } } } } }, "409": { "description": "The claim is locked or does not accept alerts, an alert in alert_ids does not qualify, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The claim is locked or does not accept alerts, an alert in alert_ids does not qualify, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/dismiss": { "post": { "operationId": "bulkDismissAlerts", "summary": "Dismiss selected alerts", "tags": ["Alerts"], "description": "Dismisses the selected alerts with one optional category and note, recorded once per agreement. Dismissal keeps any claim attachment. A filter without statuses also dismisses claimed alerts. A dismissal with a category or note starts one agreement_context_suggestions workflow run per agreement, which may propose edits to that agreement's instructions for review. The command does not wait for it. A filter leaves credited alerts alone and counts them in skipped_count; select one with alert_ids to change it. Select alerts with alert_ids or with filter. The command is one transaction and changes at most 5000 alerts; a filter that would change more returns 409 and changes nothing. Matching alerts already in the requested state, or left alone, do not count toward the limit, so a retry is safe. A filter must name topic_ids or claim_ids without null, agreement_ids, or invoice_ids. Alerts in completed claims may not be changed.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Explicit alerts. The command applies to every listed alert or fails: an unknown ID returns 404 and an alert that may not be changed returns 409." }, "filter": { "type": "object", "properties": { "mine": { "type": "boolean", "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "team_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "claim_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "has_claim": { "type": "boolean", "description": "Use false to select alerts that are not currently attached to any claim." }, "claim_statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "minItems": 1, "maxItems": 50, "description": "Match alerts whose current claim has any of these statuses." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on any of these invoices." }, "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these agreements." }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these suppliers." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "topic_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "excluded_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "has_topic": { "type": "boolean", "description": "Use false to select uncategorized alerts." }, "statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "minItems": 1, "maxItems": 50 }, "confidence_levels": { "type": "array", "items": { "type": "string", "enum": ["high", "mid", "low", "null"] }, "minItems": 1, "maxItems": 50, "description": "Match any listed confidence level; null matches alerts without one." }, "currency_codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 1, "maxItems": 50 }, "correction_types": { "type": "array", "items": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "minItems": 1, "maxItems": 50 }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "impact_min": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "impact_max": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "issued_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "issued_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "created_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "created_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." } }, "additionalProperties": false, "description": "Every alert matching this filter when the command runs. Takes the GET /v1/alerts filters with JSON lists and booleans. Matching alerts that may not be changed are left alone and counted in skipped_count." }, "excluded_alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Alerts to leave out of a filter selection. Only valid with filter." }, "category": { "type": ["string", "null"], "enum": [ "wrong_alert", "valid_not_actioning", "already_handled", "duplicate_covered", "other", null ] }, "note": { "type": ["string", "null"], "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "How many alerts changed and how many matching alerts were left alone.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSelectionResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "An alert in alert_ids, or a selected team, was not found. Also returned when a selected alert is deleted while the command runs; retry.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "An alert in alert_ids, or a selected team, was not found. Also returned when a selected alert is deleted while the command runs; retry.", "request_id": "req_example" } } } } }, "409": { "description": "An alert in alert_ids belongs to a completed claim or is claimed without a claim, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "An alert in alert_ids belongs to a completed claim or is claimed without a claim, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/credit": { "post": { "operationId": "bulkCreditAlerts", "summary": "Mark selected alerts as credited", "tags": ["Alerts"], "description": "Records that the supplier has credited the selected alerts. Only the status changes: claim attachments are kept and no claim amount is recorded. A later change in credit-note coverage does not revert a credit set through this command. Select alerts with alert_ids or with filter. The command is one transaction and changes at most 5000 alerts; a filter that would change more returns 409 and changes nothing. Matching alerts already in the requested state, or left alone, do not count toward the limit, so a retry is safe. A filter must name topic_ids or claim_ids without null, agreement_ids, or invoice_ids. Alerts in completed claims may not be changed. No workflow starts.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Explicit alerts. The command applies to every listed alert or fails: an unknown ID returns 404 and an alert that may not be changed returns 409." }, "filter": { "type": "object", "properties": { "mine": { "type": "boolean", "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "team_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "claim_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "has_claim": { "type": "boolean", "description": "Use false to select alerts that are not currently attached to any claim." }, "claim_statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "minItems": 1, "maxItems": 50, "description": "Match alerts whose current claim has any of these statuses." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on any of these invoices." }, "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these agreements." }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these suppliers." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "topic_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "excluded_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "has_topic": { "type": "boolean", "description": "Use false to select uncategorized alerts." }, "statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "minItems": 1, "maxItems": 50 }, "confidence_levels": { "type": "array", "items": { "type": "string", "enum": ["high", "mid", "low", "null"] }, "minItems": 1, "maxItems": 50, "description": "Match any listed confidence level; null matches alerts without one." }, "currency_codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 1, "maxItems": 50 }, "correction_types": { "type": "array", "items": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "minItems": 1, "maxItems": 50 }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "impact_min": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "impact_max": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "issued_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "issued_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "created_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "created_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." } }, "additionalProperties": false, "description": "Every alert matching this filter when the command runs. Takes the GET /v1/alerts filters with JSON lists and booleans. Matching alerts that may not be changed are left alone and counted in skipped_count." }, "excluded_alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Alerts to leave out of a filter selection. Only valid with filter." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "How many alerts changed and how many matching alerts were left alone.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSelectionResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "An alert in alert_ids, or a selected team, was not found. Also returned when a selected alert is deleted while the command runs; retry.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "An alert in alert_ids, or a selected team, was not found. Also returned when a selected alert is deleted while the command runs; retry.", "request_id": "req_example" } } } } }, "409": { "description": "An alert in alert_ids belongs to a completed claim or is claimed without a claim, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "An alert in alert_ids belongs to a completed claim or is claimed without a claim, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/reopen": { "post": { "operationId": "bulkReopenAlerts", "summary": "Reopen selected alerts", "tags": ["Alerts"], "description": "Sets the selected alerts back to pending. Members of an active claim stay attached; members of a cancelled claim are released. A filter leaves credited alerts alone and counts them in skipped_count; select one with alert_ids to change it. Select alerts with alert_ids or with filter. The command is one transaction and changes at most 5000 alerts; a filter that would change more returns 409 and changes nothing. Matching alerts already in the requested state, or left alone, do not count toward the limit, so a retry is safe. A filter must name topic_ids or claim_ids without null, agreement_ids, or invoice_ids. Alerts in completed claims may not be changed. No workflow starts.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Explicit alerts. The command applies to every listed alert or fails: an unknown ID returns 404 and an alert that may not be changed returns 409." }, "filter": { "type": "object", "properties": { "mine": { "type": "boolean", "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "team_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "claim_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "has_claim": { "type": "boolean", "description": "Use false to select alerts that are not currently attached to any claim." }, "claim_statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "minItems": 1, "maxItems": 50, "description": "Match alerts whose current claim has any of these statuses." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on any of these invoices." }, "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these agreements." }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these suppliers." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "topic_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "excluded_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "has_topic": { "type": "boolean", "description": "Use false to select uncategorized alerts." }, "statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "minItems": 1, "maxItems": 50 }, "confidence_levels": { "type": "array", "items": { "type": "string", "enum": ["high", "mid", "low", "null"] }, "minItems": 1, "maxItems": 50, "description": "Match any listed confidence level; null matches alerts without one." }, "currency_codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 1, "maxItems": 50 }, "correction_types": { "type": "array", "items": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "minItems": 1, "maxItems": 50 }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "impact_min": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "impact_max": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "issued_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "issued_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "created_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "created_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." } }, "additionalProperties": false, "description": "Every alert matching this filter when the command runs. Takes the GET /v1/alerts filters with JSON lists and booleans. Matching alerts that may not be changed are left alone and counted in skipped_count." }, "excluded_alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Alerts to leave out of a filter selection. Only valid with filter." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "How many alerts changed and how many matching alerts were left alone.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSelectionResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "An alert in alert_ids, or a selected team, was not found. Also returned when a selected alert is deleted while the command runs; retry.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "An alert in alert_ids, or a selected team, was not found. Also returned when a selected alert is deleted while the command runs; retry.", "request_id": "req_example" } } } } }, "409": { "description": "An alert in alert_ids belongs to a completed claim or is claimed without a claim, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "An alert in alert_ids belongs to a completed claim or is claimed without a claim, the filter selects too many alerts, a selected alert changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/export": { "get": { "operationId": "exportAlerts", "summary": "Export selected alerts", "tags": ["Alerts"], "description": "Exports every alert matching the list filters, newest first, with its invoice line, expected values, confidence and organization-currency impact. Dates use the organization timezone. CSV streams: success requires reading the whole body, and a failure after streaming starts ends the download. XLSX is generated completely before the response and adds a Topics sheet with the topics of the exported alerts and their totals over the export. Does not accept list cursors or sorting. Not a snapshot: filters are reapplied per batch. Use parseAs: stream with the generated client.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "required": false, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses.", "name": "claim_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Use false to select alerts that are not currently attached to any claim." }, "required": false, "description": "Use false to select alerts that are not currently attached to any claim.", "name": "has_claim", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts whose current claim has any of these statuses." }, "required": false, "description": "Match alerts whose current claim has any of these statuses.", "name": "claim_statuses", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "invoice_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts on any of these invoices." }, "required": false, "description": "Leave out alerts on any of these invoices.", "name": "excluded_invoice_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts for any of these agreements." }, "required": false, "description": "Leave out alerts for any of these agreements.", "name": "excluded_agreement_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts for any of these suppliers." }, "required": false, "description": "Leave out alerts for any of these suppliers.", "name": "excluded_supplier_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "recipient_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "required": false, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match.", "name": "excluded_recipient_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tag_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "required": false, "description": "Match alerts in any selected topic; null matches uncategorized alerts.", "name": "topic_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "required": false, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match.", "name": "excluded_topic_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Use false to select uncategorized alerts." }, "required": false, "description": "Use false to select uncategorized alerts.", "name": "has_topic", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "statuses", "in": "query" }, { "schema": { "type": "string", "description": "Match any listed confidence level; null matches alerts without one." }, "required": false, "description": "Match any listed confidence level; null matches alerts without one.", "name": "confidence_levels", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "currency_codes", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "correction_types", "in": "query" }, { "schema": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "required": false, "name": "freshness", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "required": false, "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match.", "name": "impact_min", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "required": false, "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match.", "name": "impact_max", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "required": false, "description": "Invoice issued on or after this date.", "name": "issued_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "required": false, "description": "Invoice issued on or before this date.", "name": "issued_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "required": false, "description": "Created on or after this calendar date in the organization's timezone.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "required": false, "description": "Created on or before this calendar date in the organization's timezone.", "name": "created_through", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." }, "required": false, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID.", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": ["csv", "xlsx"], "default": "csv", "description": "xlsx adds a Topics sheet with the topics of the exported alerts." }, "required": false, "description": "xlsx adds a Topics sheet with the topics of the exported alerts.", "name": "format", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The export file. Content type follows format.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "required": true }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": true } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts": { "get": { "operationId": "listAlerts", "summary": "List alerts", "tags": ["Alerts"], "description": "Lists all retained alerts by default, including dismissed and outdated alerts. Filter by resource IDs or statuses; use topic_ids=null for uncategorized alerts. Currency amounts are exact decimal strings.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "required": false, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses.", "name": "claim_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Use false to select alerts that are not currently attached to any claim." }, "required": false, "description": "Use false to select alerts that are not currently attached to any claim.", "name": "has_claim", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts whose current claim has any of these statuses." }, "required": false, "description": "Match alerts whose current claim has any of these statuses.", "name": "claim_statuses", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "invoice_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts on any of these invoices." }, "required": false, "description": "Leave out alerts on any of these invoices.", "name": "excluded_invoice_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts for any of these agreements." }, "required": false, "description": "Leave out alerts for any of these agreements.", "name": "excluded_agreement_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts for any of these suppliers." }, "required": false, "description": "Leave out alerts for any of these suppliers.", "name": "excluded_supplier_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "recipient_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "required": false, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match.", "name": "excluded_recipient_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tag_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "required": false, "description": "Match alerts in any selected topic; null matches uncategorized alerts.", "name": "topic_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "required": false, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match.", "name": "excluded_topic_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Use false to select uncategorized alerts." }, "required": false, "description": "Use false to select uncategorized alerts.", "name": "has_topic", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "statuses", "in": "query" }, { "schema": { "type": "string", "description": "Match any listed confidence level; null matches alerts without one." }, "required": false, "description": "Match any listed confidence level; null matches alerts without one.", "name": "confidence_levels", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "currency_codes", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "correction_types", "in": "query" }, { "schema": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "required": false, "name": "freshness", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "required": false, "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match.", "name": "impact_min", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "required": false, "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match.", "name": "impact_max", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "required": false, "description": "Invoice issued on or after this date.", "name": "issued_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "required": false, "description": "Invoice issued on or before this date.", "name": "issued_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "required": false, "description": "Created on or after this calendar date in the organization's timezone.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "required": false, "description": "Created on or before this calendar date in the organization's timezone.", "name": "created_through", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." }, "required": false, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID.", "name": "search", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "created_at", "impact_amount", "issued_date", "invoice_number", "supplier", "status" ], "default": "created_at", "description": "impact_amount compares organization-currency impact. status sorts alphabetically. Nulls sort last in both directions." }, "required": false, "description": "impact_amount compares organization-currency impact. status sorts alphabetically. Nulls sort last in both directions.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "required": false, "name": "direction", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of alerts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertSummary" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/metrics": { "get": { "operationId": "getAlertMetrics", "summary": "Get alert totals", "tags": ["Alerts"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "required": false, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses.", "name": "claim_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Use false to select alerts that are not currently attached to any claim." }, "required": false, "description": "Use false to select alerts that are not currently attached to any claim.", "name": "has_claim", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts whose current claim has any of these statuses." }, "required": false, "description": "Match alerts whose current claim has any of these statuses.", "name": "claim_statuses", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "invoice_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts on any of these invoices." }, "required": false, "description": "Leave out alerts on any of these invoices.", "name": "excluded_invoice_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts for any of these agreements." }, "required": false, "description": "Leave out alerts for any of these agreements.", "name": "excluded_agreement_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts for any of these suppliers." }, "required": false, "description": "Leave out alerts for any of these suppliers.", "name": "excluded_supplier_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "recipient_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "required": false, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match.", "name": "excluded_recipient_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tag_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "required": false, "description": "Match alerts in any selected topic; null matches uncategorized alerts.", "name": "topic_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "required": false, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match.", "name": "excluded_topic_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Use false to select uncategorized alerts." }, "required": false, "description": "Use false to select uncategorized alerts.", "name": "has_topic", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "statuses", "in": "query" }, { "schema": { "type": "string", "description": "Match any listed confidence level; null matches alerts without one." }, "required": false, "description": "Match any listed confidence level; null matches alerts without one.", "name": "confidence_levels", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "currency_codes", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "correction_types", "in": "query" }, { "schema": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "required": false, "name": "freshness", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "required": false, "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match.", "name": "impact_min", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "required": false, "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match.", "name": "impact_max", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "required": false, "description": "Invoice issued on or after this date.", "name": "issued_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "required": false, "description": "Invoice issued on or before this date.", "name": "issued_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "required": false, "description": "Created on or after this calendar date in the organization's timezone.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "required": false, "description": "Created on or before this calendar date in the organization's timezone.", "name": "created_through", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." }, "required": false, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID.", "name": "search", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Counts, distinct invoices, and amounts per currency and in the organization currency, using the same filters as the alert list.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertMetrics" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/groups": { "get": { "operationId": "listAlertGroups", "summary": "List alert group summaries", "tags": ["Alerts"], "description": "Returns the metrics of each group of matching alerts, by agreement, invoice, topic, claim, status, or freshness. A group's key, put in its dimension filter (agreement_ids, invoice_ids, topic_ids, claim_ids, statuses, freshness; null as the string null), lists or counts exactly that group, so the same endpoint with the parent key added returns subgroups. Only groups with matching alerts are returned.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "required": false, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses.", "name": "claim_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Use false to select alerts that are not currently attached to any claim." }, "required": false, "description": "Use false to select alerts that are not currently attached to any claim.", "name": "has_claim", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts whose current claim has any of these statuses." }, "required": false, "description": "Match alerts whose current claim has any of these statuses.", "name": "claim_statuses", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "invoice_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts on any of these invoices." }, "required": false, "description": "Leave out alerts on any of these invoices.", "name": "excluded_invoice_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts for any of these agreements." }, "required": false, "description": "Leave out alerts for any of these agreements.", "name": "excluded_agreement_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts for any of these suppliers." }, "required": false, "description": "Leave out alerts for any of these suppliers.", "name": "excluded_supplier_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "recipient_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "required": false, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match.", "name": "excluded_recipient_ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tag_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "required": false, "description": "Match alerts in any selected topic; null matches uncategorized alerts.", "name": "topic_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "required": false, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match.", "name": "excluded_topic_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Use false to select uncategorized alerts." }, "required": false, "description": "Use false to select uncategorized alerts.", "name": "has_topic", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "statuses", "in": "query" }, { "schema": { "type": "string", "description": "Match any listed confidence level; null matches alerts without one." }, "required": false, "description": "Match any listed confidence level; null matches alerts without one.", "name": "confidence_levels", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "currency_codes", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "correction_types", "in": "query" }, { "schema": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "required": false, "name": "freshness", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "required": false, "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match.", "name": "impact_min", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "required": false, "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match.", "name": "impact_max", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "required": false, "description": "Invoice issued on or after this date.", "name": "issued_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "required": false, "description": "Invoice issued on or before this date.", "name": "issued_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "required": false, "description": "Created on or after this calendar date in the organization's timezone.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "required": false, "description": "Created on or before this calendar date in the organization's timezone.", "name": "created_through", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." }, "required": false, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID.", "name": "search", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": ["agreement", "invoice", "topic", "claim", "status", "freshness"] }, "required": true, "name": "group_by", "in": "query" }, { "schema": { "type": "string", "enum": ["impact_amount", "total_count", "title"], "default": "impact_amount", "description": "impact_amount compares organization_currency.impact_amount." }, "required": false, "description": "impact_amount compares organization_currency.impact_amount.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "required": false, "name": "direction", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of alert group summaries with status counts and totals per currency.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertGroup" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/{id}": { "get": { "operationId": "getAlert", "summary": "Get an alert", "tags": ["Alerts"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The alert with its current edit revision.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." }, "required": true, "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateAlert", "summary": "Edit an alert", "tags": ["Alerts"], "description": "Use the same field names and nesting as GET. Send only fields to change, including individual fields inside expected; omitted fields are preserved and null clears a nullable field. Use exact decimal strings and rates as fractions. expected.net_price and expected.total are calculated and read-only. invoiced, invoice_item, provenance, and status are read-only. citations accepts explicit upsert/remove changes by source_ref; omitted citations and fields are preserved. Field edits update the shared citation in every linked alert/topic; citation selectors relink only this alert. Shared edits are blocked by protected claims or locked topics. Document edits are re-verified against stored text; verification and metadata are server-owned. Inline markers must resolve against the resulting collection. Saving does not start checks or model work.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The exact ETag from GET /v1/alerts/{id} or the preceding edit." }, "required": true, "description": "The exact ETag from GET /v1/alerts/{id} or the preceding edit.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "citations": { "type": "object", "properties": { "upsert": { "type": "array", "items": { "type": "object", "properties": { "source_ref": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "source": { "anyOf": [ { "type": "object", "properties": { "source_type": { "type": "string", "enum": ["document"] }, "document_id": { "type": "string", "format": "uuid" } }, "required": ["source_type", "document_id"], "additionalProperties": false }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": ["web"] }, "url": { "type": "string", "maxLength": 20000 } }, "required": ["source_type", "url"], "additionalProperties": false }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": ["agreement_items"] }, "item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } }, "required": ["source_type", "item_ids"], "additionalProperties": false }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": ["user_context"] }, "text": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": ["source_type", "text"], "additionalProperties": false } ] }, "quote": { "type": ["string", "null"], "maxLength": 20000 }, "text": { "type": ["string", "null"], "maxLength": 20000 }, "page": { "type": ["string", "null"], "maxLength": 20000 }, "section_title": { "type": ["string", "null"], "maxLength": 20000 }, "context_before": { "type": ["string", "null"], "maxLength": 20000 }, "context_after": { "type": ["string", "null"], "maxLength": 20000 }, "title": { "type": ["string", "null"], "maxLength": 20000 }, "citation": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": ["id"], "additionalProperties": false }, { "type": "object", "properties": { "source": { "anyOf": [ { "type": "object", "properties": { "source_type": { "type": "string", "enum": ["document"] }, "document_id": { "type": "string", "format": "uuid" } }, "required": ["source_type", "document_id"], "additionalProperties": false }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": ["web"] }, "url": { "type": "string", "maxLength": 20000 } }, "required": ["source_type", "url"], "additionalProperties": false }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": ["agreement_items"] }, "item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } }, "required": ["source_type", "item_ids"], "additionalProperties": false }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": ["user_context"] }, "text": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": ["source_type", "text"], "additionalProperties": false } ] }, "quote": { "type": ["string", "null"], "maxLength": 20000 }, "text": { "type": ["string", "null"], "maxLength": 20000 }, "page": { "type": ["string", "null"], "maxLength": 20000 }, "section_title": { "type": ["string", "null"], "maxLength": 20000 }, "context_before": { "type": ["string", "null"], "maxLength": 20000 }, "context_after": { "type": ["string", "null"], "maxLength": 20000 }, "title": { "type": ["string", "null"], "maxLength": 20000 } }, "required": ["source"], "additionalProperties": false } ] } }, "required": ["source_ref"], "additionalProperties": false }, "maxItems": 100, "default": [] }, "remove": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "maxItems": 100, "default": [] } }, "additionalProperties": false }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "explanation": { "type": ["string", "null"], "maxLength": 20000 }, "questions": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 50 }, "expected": { "type": "object", "properties": { "base_price": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "quantity": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "adjustment_uplift": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "price_explanation": { "type": ["string", "null"], "maxLength": 20000 }, "adjustment_explanation": { "type": ["string", "null"], "maxLength": 20000 }, "product_code": { "type": ["string", "null"], "maxLength": 2000 }, "description": { "type": ["string", "null"], "maxLength": 20000 }, "unit": { "type": ["string", "null"], "maxLength": 2000 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The alert with its current edit revision.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." }, "required": true, "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The alert belongs to a completed claim, or this status transition is incompatible.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The alert belongs to a completed claim, or this status transition is incompatible.", "request_id": "req_example" } } } } }, "412": { "description": "The alert changed since the supplied ETag was read. Retrieve it again before editing.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The alert changed since the supplied ETag was read. Retrieve it again before editing.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/{id}/dismiss": { "post": { "operationId": "dismissAlert", "summary": "Dismiss an alert", "tags": ["Alerts"], "description": "Records dismissal feedback and a snapshot. Send {} when no feedback is needed. Dismissal keeps any claim attachment and changes the alert status only. Repeating a dismissal is a no-op. A dismissal with a category or note starts one agreement_context_suggestions workflow run per agreement, which may propose edits to that agreement's instructions for review. The command does not wait for it.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": ["string", "null"], "enum": [ "wrong_alert", "valid_not_actioning", "already_handled", "duplicate_covered", "other", null ] }, "note": { "type": ["string", "null"], "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The alert with its current edit revision.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." }, "required": true, "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The alert belongs to a completed claim, or this status transition is incompatible.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The alert belongs to a completed claim, or this status transition is incompatible.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/{id}/credit": { "post": { "operationId": "creditAlert", "summary": "Mark an alert as credited", "tags": ["Alerts"], "description": "Records that the supplier has credited this alert. Only the status changes: any claim attachment is kept and no claim amount is recorded. A later change in credit-note coverage does not revert it. Credited is a no-op.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The alert with its current edit revision.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." }, "required": true, "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The alert belongs to a completed claim, or this status transition is incompatible.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The alert belongs to a completed claim, or this status transition is incompatible.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alerts/{id}/reopen": { "post": { "operationId": "reopenAlert", "summary": "Reopen an alert", "tags": ["Alerts"], "description": "Sets an alert back to pending. Members of a pending or in-progress claim stay attached; members of a cancelled claim are released. Pending is a no-op. Existing dismissal snapshots remain unchanged.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The alert with its current edit revision.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." }, "required": true, "description": "Opaque revision of the stored alert. Send it unchanged in If-Match when editing." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The alert belongs to a completed claim, or this status transition is incompatible.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The alert belongs to a completed claim, or this status transition is incompatible.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topics": { "get": { "operationId": "listAlertTopics", "summary": "List alert topics", "tags": ["Alerts"], "description": "Lists existing topics, including empty topics. Ordered by ID. Topics are created by alert categorization and by applied merge or split proposals; they cannot be created or deleted one at a time.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "search", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of topics.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertTopic" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topics/{id}": { "get": { "operationId": "getAlertTopic", "summary": "Get an alert topic", "tags": ["Alerts"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The topic, its alert counts and its citations.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTopicDetail" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateAlertTopic", "summary": "Edit an alert topic", "tags": ["Alerts"], "description": "Edits the title, description, and key questions. Text is trimmed and an empty string clears the field. The description is Markdown; inline citations must use the source numbers stored for the topic. A locked topic returns 409; unlock it first. Sending the current values changes nothing. The last write wins. No model work or categorization starts.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": ["string", "null"], "maxLength": 200 }, "description": { "type": ["string", "null"], "maxLength": 100000, "description": "Markdown. Inline citations such as [1] or [1,2] must use the source numbers stored for this topic." }, "key_questions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20000 }, "maxItems": 100, "description": "Replaces the questions. Send an empty list to clear them." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The topic, its alert counts and its citations.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTopicDetail" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The topic is locked.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The topic is locked.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topics/{id}/lock": { "post": { "operationId": "lockAlertTopic", "summary": "Lock an alert topic", "tags": ["Alerts"], "description": "Protects the topic from automatic categorization, merging, splitting, deletion, and edits to its title, description, and key questions. Alerts can still be moved in and out. Locking a locked topic changes nothing.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The topic, its alert counts and its citations.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTopicDetail" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topics/{id}/unlock": { "post": { "operationId": "unlockAlertTopic", "summary": "Unlock an alert topic", "tags": ["Alerts"], "description": "Lets automatic categorization and edits change the topic again. Unlocking an unlocked topic changes nothing.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The topic, its alert counts and its citations.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTopicDetail" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topics/{id}/alerts": { "post": { "operationId": "assignAlertTopicAlerts", "summary": "Move alerts into a topic", "tags": ["Alerts"], "description": "Puts the selected alerts in this topic, moving them out of any other topic. An alert has at most one topic; emptied topics are kept. Alerts already in this topic are left alone. Topic locks do not restrict membership. With alert_ids, an alert outside the topic agreement returns 404. A filter covers alerts in the topic agreement; use topic_ids to move a whole topic, or topic_ids=[\"null\"] (has_topic=false) for uncategorized alerts. Select alerts with alert_ids or with filter. The command is one transaction and changes at most 5000 alerts; a filter that would change more returns 409 and changes nothing. Matching alerts already in the requested state, or left alone, do not count toward the limit, so a retry is safe.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Explicit alerts. The command applies to every listed alert or fails: an unknown ID returns 404 and an alert that may not be changed returns 409." }, "filter": { "type": "object", "properties": { "mine": { "type": "boolean", "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "team_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "claim_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts currently attached to any selected claim; null matches alerts in no claim. Removed or transferred attachments are excluded. Claim status does not restrict matches; use claim_statuses." }, "has_claim": { "type": "boolean", "description": "Use false to select alerts that are not currently attached to any claim." }, "claim_statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"] }, "minItems": 1, "maxItems": 50, "description": "Match alerts whose current claim has any of these statuses." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on any of these invoices." }, "agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_agreement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these agreements." }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts for any of these suppliers." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "excluded_recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts on invoices for any of these recipients. Alerts on invoices without a recipient still match." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "topic_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Match alerts in any selected topic; null matches uncategorized alerts." }, "excluded_topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Leave out alerts in any of these topics. Uncategorized alerts still match." }, "has_topic": { "type": "boolean", "description": "Use false to select uncategorized alerts." }, "statuses": { "type": "array", "items": { "type": "string", "enum": ["pending", "claimed", "dismissed", "credited"] }, "minItems": 1, "maxItems": 50 }, "confidence_levels": { "type": "array", "items": { "type": "string", "enum": ["high", "mid", "low", "null"] }, "minItems": 1, "maxItems": 50, "description": "Match any listed confidence level; null matches alerts without one." }, "currency_codes": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 1, "maxItems": 50 }, "correction_types": { "type": "array", "items": { "type": "string", "enum": ["modify_item", "modify_invoice", "add_item"] }, "minItems": 1, "maxItems": 50 }, "freshness": { "type": "string", "enum": ["current", "outdated", "unknown"] }, "impact_min": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Minimum impact in the organization currency, inclusive. Alerts without an impact never match." }, "impact_max": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Maximum impact in the organization currency, inclusive. Alerts without an impact never match." }, "issued_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or after this date." }, "issued_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice issued on or before this date." }, "created_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or after this calendar date in the organization's timezone." }, "created_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Created on or before this calendar date in the organization's timezone." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Matches, ignoring case, the alert title, explanation and expected line; the supplier; the invoice number, title and line; the agreement title; or the topic title and description. A UUID also matches the alert, invoice, supplier or agreement ID." } }, "additionalProperties": false, "description": "Every alert matching this filter when the command runs. Takes the GET /v1/alerts filters with JSON lists and booleans. Matching alerts that may not be changed are left alone and counted in skipped_count." }, "excluded_alert_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000, "description": "Alerts to leave out of a filter selection. Only valid with filter." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "How many alerts moved into the topic. skipped_count is always 0.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSelectionResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The filter selects too many alerts, topic membership changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The filter selects too many alerts, topic membership changed while the command ran, or a selected team has invalid saved rules. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topic-proposals": { "post": { "operationId": "createAlertTopicProposal", "summary": "Propose a topic merge or split", "tags": ["Alerts"], "description": "Starts preparing new topics for the selected topics of one agreement. A merge proposes one topic for all their alerts; a split proposes two or more topics and assigns every alert group to one of them. Alerts that replace, or are replaced by, alerts in the selection are included. Nothing changes until the proposal is applied. When the workflow run completes, its item result holds proposal_id; read it with GET /v1/alert-topic-proposals/{id}. A locked topic returns 409.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "enum": ["merge", "split"] }, "topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 }, "instructions": { "type": "string", "maxLength": 4000, "description": "Split only. What the reviewer wants the new topics to separate." } }, "required": ["operation", "topic_ids"], "additionalProperties": false } } } }, "responses": { "202": { "description": "Proposal admitted and execution acceptance confirmed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "A selected topic is locked, or the admitted run ended before its execution was recorded.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "A selected topic is locked, or the admitted run ended before its execution was recorded.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "The run could not be started, or its acceptance is unconfirmed. Follow Location to inspect the workflow run before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "The run could not be started, or its acceptance is unconfirmed. Follow Location to inspect the workflow run before retrying.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topic-proposals/{id}": { "get": { "operationId": "getAlertTopicProposal", "summary": "Get a topic proposal", "tags": ["Alerts"], "description": "The proposed topics, their citations and where each alert group goes. applied_at is set once the proposal has been applied.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The topic proposal.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTopicProposal" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/alert-topic-proposals/{id}/apply": { "post": { "operationId": "applyAlertTopicProposal", "summary": "Apply a topic proposal", "tags": ["Alerts"], "description": "Creates the proposed topics with any edits, moves every alert of the proposal into its topic and deletes the selected topics, in one transaction. Send {} to apply the proposal as it is. Edited descriptions and questions may cite only the topic’s own citation numbers. A proposal applies once, and only while the agreement’s topics and memberships are as they were when it was prepared; otherwise request a new proposal.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "pattern": "^NT\\d+$" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 20000, "description": "Markdown. Inline citations such as [1] use the numbers of the topic sources." }, "key_questions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20000 }, "maxItems": 100 } }, "required": ["ref"], "additionalProperties": false }, "maxItems": 12, "description": "Edits to proposed topics. Omitted topics and fields are applied as proposed." }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "group_ref": { "type": "string", "pattern": "^(A|G|R)\\d+$" }, "topic_ref": { "type": "string", "pattern": "^NT\\d+$" } }, "required": ["group_ref", "topic_ref"], "additionalProperties": false }, "maxItems": 10000, "description": "Split only. Moves alert groups between the proposed topics." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The topics were changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTopicProposalResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The proposal was already applied, topics changed since it was prepared, or an affected topic is locked. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The proposal was already applied, topics changed since it was prepared, or an affected topic is locked. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/tags": { "get": { "operationId": "listAgreementTags", "summary": "List agreement tags", "description": "Lists the organization tag catalogue, including unassigned tags. Ordered by case-insensitive name, then ID. Use search for a picker or ids to resolve known tags. Cursors are bound to the organization and filters. Assigned tags are also returned in full on each agreement.", "tags": ["Agreement tags"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive literal substring of the tag name." }, "required": false, "description": "Case-insensitive literal substring of the tag name.", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated tag IDs to resolve within this organization." }, "required": false, "description": "Comma-separated tag IDs to resolve within this organization.", "name": "ids", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Organization tag catalogue.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createAgreementTag", "summary": "Create an agreement tag", "description": "Creates an organization tag with a trimmed name of 1–80 characters. Names are unique case-insensitively within the organization: repeating a name returns the existing tag with 200 and preserves its spelling; a new tag returns 201. Location identifies the catalogue filtered to the returned ID. Assign it using tag_ids on agreement creation or PATCH. Creating a tag does not assign it or start workflows.", "tags": ["Agreement tags"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Existing tag with the same case-insensitive name.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": ["id", "name"] } } } }, "201": { "description": "Tag created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": ["id", "name"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "Tag changed concurrently during creation. Retry the request.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Tag changed concurrently during creation. Retry the request.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements": { "get": { "operationId": "listAgreements", "summary": "List agreements", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring search across agreement titles and linked supplier names." }, "required": false, "description": "Case-insensitive substring search across agreement titles and linked supplier names.", "name": "search", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "statuses", "in": "query" }, { "schema": { "type": "string", "description": "Agreements with at least one of these organization-owned suppliers selected." }, "required": false, "description": "Agreements with at least one of these organization-owned suppliers selected.", "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Agreements covering any of these organization-owned recipients, including agreements with no recipient restriction." }, "required": false, "description": "Agreements covering any of these organization-owned recipients, including agreements with no recipient restriction.", "name": "recipient_ids", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated organization tag IDs. Matches agreements with any of these tags; combines with other filters using AND." }, "required": false, "description": "Comma-separated organization tag IDs. Matches agreements with any of these tags; combines with other filters using AND.", "name": "tag_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out agreements with any of these suppliers selected." }, "required": false, "description": "Leave out agreements with any of these suppliers selected.", "name": "excluded_supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Leave out agreements with any of these tags." }, "required": false, "description": "Leave out agreements with any of these tags.", "name": "excluded_tag_ids", "in": "query" }, { "schema": { "type": "string", "description": "Agreements with at least one alert in any of these statuses." }, "required": false, "description": "Agreements with at least one alert in any of these statuses.", "name": "has_alert_statuses", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "effective_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "effective_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "expiration_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "expiration_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "valid_on", "in": "query" }, { "schema": { "type": "string", "enum": [ "created_at", "title", "effective_date", "expiration_date", "supplier", "pending_topic_count", "alert_progress", "open_alert_impact" ], "default": "created_at", "description": "supplier sorts by the alphabetically first supplier. alert_progress is the share of alerts that are not pending (agreements without alerts last). open_alert_impact sums pending and claimed impact in the organization currency." }, "required": false, "description": "supplier sorts by the alphabetically first supplier. alert_progress is the share of alerts that are not pending (agreements without alerts last). open_alert_impact sums pending and claimed impact in the organization currency.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "required": false, "name": "direction", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Agreement summaries with complete supplier, recipient and tag arrays.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementSummary" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createAgreement", "summary": "Create an agreement", "description": "Accepts all editable agreement fields, including status. Status defaults to draft; active requires a nonblank title. Agreements, prices and document relationships remain editable in every status. An empty object creates a draft. No processing or matching is started. Optional Idempotency-Key safely replays creation.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["draft", "active", "archived"], "default": "draft", "description": "Initial status. Active agreements require a nonblank title. All statuses remain editable." }, "title": { "type": ["string", "null"], "maxLength": 500, "default": null }, "effective_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "expiration_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Complete supplier selection. An empty array matches no invoices." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Complete recipient selection. An empty array removes the recipient restriction." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Complete set of existing organization tag IDs. An empty array removes all tags. Tags organize agreements and do not affect invoice matching or compliance freshness." }, "applicability": { "type": ["object", "null"], "properties": { "match": { "type": "string", "enum": ["all", "any"] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["contains"] }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["not_contains"] }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["in"] }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minItems": 1, "maxItems": 100 } }, "required": ["field", "operator", "values"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["not_in"] }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minItems": 1, "maxItems": 100 } }, "required": ["field", "operator", "values"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["is_empty"] } }, "required": ["field", "operator"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["is_not_empty"] } }, "required": ["field", "operator"], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 100 } }, "default": null, "required": ["match", "conditions"], "additionalProperties": false }, "renewal": { "type": ["object", "null"], "properties": { "mode": { "type": ["string", "null"], "enum": ["none", "optional", "automatic", null], "default": null }, "period": { "type": ["object", "null"], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "unit": { "type": "string", "enum": ["days", "weeks", "months", "years"] } }, "default": null, "required": ["value", "unit"], "additionalProperties": false }, "occurrences_remaining": { "type": ["integer", "null"], "minimum": 0, "maximum": 2147483647, "default": null }, "notice_period": { "type": ["object", "null"], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "unit": { "type": "string", "enum": ["days", "weeks", "months", "years"] } }, "default": null, "required": ["value", "unit"], "additionalProperties": false }, "deadline_override": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "default": null, "additionalProperties": false }, "instructions": { "type": ["string", "null"], "maxLength": 20000, "default": null, "description": "Additional context for interpreting this agreement during compliance checks. Null clears the instructions. Saving does not run checks." }, "alert_settings": { "type": "object", "properties": { "flag_undercharges": { "type": "boolean", "default": false }, "flag_uncovered_items": { "type": "boolean", "default": false } }, "additionalProperties": false, "description": "When omitted, inherits organization agreement defaults at creation. An explicit object replaces the defaults; omitted flags within it default to false." }, "matching_settings": { "type": "object", "properties": { "smart_matching_enabled": { "type": "boolean", "default": false }, "smart_matching_criterion": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "default": null } }, "default": { "smart_matching_enabled": false, "smart_matching_criterion": null }, "additionalProperties": false, "description": "Stored smart-matching configuration. Replaces the complete object; omitted values default to false and null. Saving does not run matching." } }, "additionalProperties": false }, "example": { "title": "Support services", "status": "active", "effective_date": "2026-01-01", "expiration_date": "2026-12-31" } } } }, "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "201": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}": { "get": { "operationId": "getAgreement", "summary": "Get an agreement", "description": "Returns full agreement detail, including renewal, stored invoice applicability conditions, and complete supplier, recipient and tag arrays.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateAgreement", "summary": "Edit an agreement", "description": "Omitted fields are preserved; null clears nullable fields. Supplied nested objects and membership arrays replace the complete field. Set status to active to activate or reactivate, or archived to archive. Status and content changes apply atomically; the resulting active agreement requires a nonblank title. Agreements, prices and document relationships remain editable in every status. Repeating the current status without content changes is a no-op. Content may change during explicit API matching; older captured inputs cannot publish after that change. Saving starts no workflows.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412." }, "required": false, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": ["string", "null"], "maxLength": 500 }, "effective_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "expiration_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "supplier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Complete supplier selection. An empty array matches no invoices." }, "recipient_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Complete recipient selection. An empty array removes the recipient restriction." }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Complete set of existing organization tag IDs. An empty array removes all tags. Tags organize agreements and do not affect invoice matching or compliance freshness." }, "applicability": { "type": ["object", "null"], "properties": { "match": { "type": "string", "enum": ["all", "any"] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["contains"] }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["not_contains"] }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["in"] }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minItems": 1, "maxItems": 100 } }, "required": ["field", "operator", "values"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["not_in"] }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minItems": 1, "maxItems": 100 } }, "required": ["field", "operator", "values"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["is_empty"] } }, "required": ["field", "operator"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "all_references", "order_references", "buyer_reference", "seller_reference", "contract_reference", "project_reference", "accounting_cost", "delivery_address", "delivery_name", "delivery_street", "delivery_postal_code", "delivery_city", "delivery_state", "delivery_country" ] }, "operator": { "type": "string", "enum": ["is_not_empty"] } }, "required": ["field", "operator"], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 100 } }, "required": ["match", "conditions"], "additionalProperties": false }, "renewal": { "type": ["object", "null"], "properties": { "mode": { "type": ["string", "null"], "enum": ["none", "optional", "automatic", null], "default": null }, "period": { "type": ["object", "null"], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "unit": { "type": "string", "enum": ["days", "weeks", "months", "years"] } }, "default": null, "required": ["value", "unit"], "additionalProperties": false }, "occurrences_remaining": { "type": ["integer", "null"], "minimum": 0, "maximum": 2147483647, "default": null }, "notice_period": { "type": ["object", "null"], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "unit": { "type": "string", "enum": ["days", "weeks", "months", "years"] } }, "default": null, "required": ["value", "unit"], "additionalProperties": false }, "deadline_override": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "additionalProperties": false }, "instructions": { "type": ["string", "null"], "maxLength": 20000, "description": "Additional context for interpreting this agreement during compliance checks. Null clears the instructions. Saving does not run checks." }, "alert_settings": { "type": "object", "properties": { "flag_undercharges": { "type": "boolean", "default": false }, "flag_uncovered_items": { "type": "boolean", "default": false } }, "additionalProperties": false, "description": "Agreement-specific alert preferences. Replaces the complete object; omitted flags default to false. Saving preferences does not run checks." }, "matching_settings": { "type": "object", "properties": { "smart_matching_enabled": { "type": "boolean", "default": false }, "smart_matching_criterion": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "default": null } }, "additionalProperties": false, "description": "Stored smart-matching configuration. Replaces the complete object; omitted values default to false and null. Saving does not run matching." }, "status": { "type": "string", "enum": ["active", "archived"], "description": "Set active to activate or reactivate, or archived to archive. All statuses remain editable. May be combined with other edits; repeating the current status is a no-op." } }, "additionalProperties": false }, "example": { "title": "Annual support services", "instructions": "Use the signed service schedule.", "alert_settings": { "flag_undercharges": false, "flag_uncovered_items": true } } } } }, "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteAgreement", "summary": "Delete an agreement", "description": "Removes the agreement from normal reads and future matching. Retains shared Documents, prices, source relationships, existing matches, assessments and evidence for historical references. Does not execute workflows. Deletion is unavailable while agreement work is in progress (409), except API classification, detail suggestions and price imports. Optional If-Match is checked atomically. Subsequent reads or edits return 404; there is no restore operation.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412." }, "required": false, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Agreement deleted." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/price-items": { "get": { "operationId": "listAgreementPriceItems", "summary": "List agreement prices", "description": "Ordered by position then UUID. Search matches description and product code; ids selects specific items; price_import_id selects the prices an import created. For conditional collection edits, use the ETag from any page without a search, ids or price_import_id filter. Limit and cursor do not change the collection validator; it covers every price, including later pages.", "tags": ["Agreement prices"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "Only these price items, for example the price_item_ids of an alert." }, "required": false, "description": "Only these price items, for example the price_item_ids of an alert.", "name": "ids", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Only prices this price import created." }, "required": false, "description": "Only prices this price import created.", "name": "price_import_id", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of price items.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for the complete price collection and its search, ids and price_import_id filters, independent of limit and cursor." }, "required": true, "description": "Strong validator for the complete price collection and its search, ids and price_import_id filters, independent of limit and cursor." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementPriceItem" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createAgreementPriceItems", "summary": "Add agreement prices", "description": "Create 1–100 prices atomically from a JSON array, including an array of one for a single price. Amounts and rates use exact decimal strings. Positions start at one and default to appending in request order. Returns the created items in request order. Idempotency-Key replays the complete request; no workflows start.", "tags": ["Agreement prices"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "price": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["amount"] }, "amount": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["type", "amount"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["rate"] }, "fraction": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "basis": { "type": ["string", "null"], "maxLength": 20000, "default": null } }, "required": ["type", "fraction"], "additionalProperties": false } ] }, "description": { "type": ["string", "null"], "maxLength": 20000, "default": null }, "product_code": { "type": ["string", "null"], "maxLength": 20000, "default": null }, "product_group": { "type": ["string", "null"], "maxLength": 20000, "default": null }, "unit": { "type": ["string", "null"], "maxLength": 20000, "default": null }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "default": null }, "discount_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": null }, "surcharge_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": null }, "vat_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": null }, "applicability": { "type": ["string", "null"], "maxLength": 20000, "default": null }, "calculation_rules": { "type": ["string", "null"], "maxLength": 20000, "default": null }, "valid_from": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "valid_until": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "position": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "required": ["price"], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "example": [ { "description": "Support hour", "unit": "hour", "currency_code": "NOK", "price": { "type": "amount", "amount": "125.50" }, "vat_rate": "0.25" }, { "description": "Service fee", "price": { "type": "rate", "fraction": "0.075", "basis": "invoice subtotal" } } ] } } }, "responses": { "200": { "description": "Price items in request order. Read an individual item to obtain its ETag.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementPriceItem" } } } } }, "201": { "description": "Created price items in request order. Location identifies the first created item.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementPriceItem" } } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateAgreementPriceItems", "summary": "Edit agreement prices", "description": "Atomically edit 1–100 prices using an array of objects containing id and changed fields. IDs must be unique and belong to this agreement. Omitted fields are preserved; null clears nullable fields; price replaces the entire amount/rate variant. Returns items in request order. Retains prior evidence and advances agreement freshness once per semantic batch.", "tags": ["Agreement prices"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional ETag from any unfiltered page of this price collection, or the preceding collection PATCH. Covers all prices, including later pages. A stale, filtered-page, or individual-item validator returns 412." }, "required": false, "description": "Optional ETag from any unfiltered page of this price collection, or the preceding collection PATCH. Covers all prices, including later pages. A stale, filtered-page, or individual-item validator returns 412.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "price": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["amount"] }, "amount": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["type", "amount"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["rate"] }, "fraction": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "basis": { "type": ["string", "null"], "maxLength": 20000, "default": null } }, "required": ["type", "fraction"], "additionalProperties": false } ] }, "description": { "type": ["string", "null"], "maxLength": 20000 }, "product_code": { "type": ["string", "null"], "maxLength": 20000 }, "product_group": { "type": ["string", "null"], "maxLength": 20000 }, "unit": { "type": ["string", "null"], "maxLength": 20000 }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$" }, "discount_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "vat_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "applicability": { "type": ["string", "null"], "maxLength": 20000 }, "calculation_rules": { "type": ["string", "null"], "maxLength": 20000 }, "valid_from": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "valid_until": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "position": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "id": { "type": "string", "format": "uuid" } }, "required": ["id"], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "example": [ { "id": "11111111-1111-4111-8111-111111111111", "price": { "type": "amount", "amount": "130.00" } } ] } } }, "responses": { "200": { "description": "Price items in request order. ETag is the updated full collection validator for the next bulk edit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for the complete, unfiltered price collection." }, "required": true, "description": "Strong validator for the complete, unfiltered price collection." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementPriceItem" } } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteAgreementPriceItems", "summary": "Remove agreement prices", "description": "Atomically remove 1–100 prices using a JSON array of unique price IDs. Every ID must belong to this agreement; a missing or unavailable item rejects the entire request. Retains pre-delete evidence and advances agreement freshness once. The JSON request body is required.", "tags": ["Agreement prices"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional ETag from any unfiltered page of this price collection, or the preceding collection PATCH. Covers all prices, including later pages. A stale, filtered-page, or individual-item validator returns 412." }, "required": false, "description": "Optional ETag from any unfiltered page of this price collection, or the preceding collection PATCH. Covers all prices, including later pages. A stale, filtered-page, or individual-item validator returns 412.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } } } }, "responses": { "204": { "description": "All requested price items removed." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/price-items/{item_id}": { "get": { "operationId": "getAgreementPriceItem", "summary": "Get an agreement price", "tags": ["Agreement prices"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "item_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementPriceItem" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateAgreementPriceItem", "summary": "Edit an agreement price", "description": "Preserves the item ID. Supplying price replaces the entire amount/rate variant. An actual content change retains the prior item as evidence and advances agreement freshness.", "tags": ["Agreement prices"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "item_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412." }, "required": false, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["amount"] }, "amount": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["type", "amount"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["rate"] }, "fraction": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "basis": { "type": ["string", "null"], "maxLength": 20000, "default": null } }, "required": ["type", "fraction"], "additionalProperties": false } ] }, "description": { "type": ["string", "null"], "maxLength": 20000 }, "product_code": { "type": ["string", "null"], "maxLength": 20000 }, "product_group": { "type": ["string", "null"], "maxLength": 20000 }, "unit": { "type": ["string", "null"], "maxLength": 20000 }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$" }, "discount_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "vat_rate": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "applicability": { "type": ["string", "null"], "maxLength": 20000 }, "calculation_rules": { "type": ["string", "null"], "maxLength": 20000 }, "valid_from": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "valid_until": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "position": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementPriceItem" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteAgreementPriceItem", "summary": "Remove an agreement price", "description": "Removes the current price and retains its pre-delete evidence. Does not remove prior checks or citations.", "tags": ["Agreement prices"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "item_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412." }, "required": false, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Price item removed." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/price-imports": { "post": { "operationId": "createAgreementPriceImport", "summary": "Import prices from a Document", "description": "Extracts the prices in one Document linked to this agreement and appends them, without review. Every extracted row gets an outcome: rows with the same product and price as an existing price or an earlier row are skipped as duplicates, rows that break the price rules are recorded as invalid, and the rest become new prices whose source is the Document. Once the import completes, download the extracted table with the outcome of every row. Existing prices are never changed. Supports PDF, XLSX, XLS, CSV, TSV, DOCX, PPTX, EML, MSG, plain text, PNG and JPEG Documents of up to 256 MiB, by declared media type. Importing the same file bytes with the same worksheets, instructions and default_currency again returns the existing import with 200 while it is queued, running or completed, and starts no work: a repeated extraction can word rows differently, and exact duplicate detection would miss them. A failed or cancelled import is retried by importing again. Poll the import until it is completed, failed or cancelled, and cancel it through its workflow run. The Document stays retained while an import references it.", "tags": ["Agreement price imports"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid", "description": "A Document linked to this agreement." }, "worksheets": { "type": ["array", "null"], "items": { "type": "string", "minLength": 1, "maxLength": 31 }, "minItems": 1, "maxItems": 500, "default": null, "description": "Excel worksheets to read, by exact name. Only for XLSX and XLS Documents; null reads every worksheet." }, "instructions": { "type": ["string", "null"], "maxLength": 20000, "default": null, "description": "Guidance for reading this document, e.g. which table or price column applies." }, "default_currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "default": null, "description": "ISO 4217 currency for created amount prices whose source states none. Rows keep the source currency." } }, "required": ["document_id"], "additionalProperties": false }, "example": { "document_id": "11111111-1111-4111-8111-111111111111", "worksheets": ["Prices 2026"], "default_currency": "NOK" } } } }, "responses": { "200": { "description": "An import of the same bytes and settings already exists and is queued, running or completed. No work started.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementPriceImport" } } } }, "202": { "description": "The import, queued for extraction.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementPriceImport" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The Document bytes are missing or changed (source_unavailable), or the import ended while it was starting (Location names it).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "The Document bytes are missing or changed (source_unavailable), or the import ended while it was starting (Location names it).", "request_id": "req_example" } } } } }, "415": { "description": "The Document's declared media type cannot be imported.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_unsupported_media_type" }, "example": { "error": { "code": "unsupported_media_type", "message": "The Document's declared media type cannot be imported.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication is unavailable or the import could not be confirmed as started. When Location is present, read the import before importing again.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": false, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication is unavailable or the import could not be confirmed as started. When Location is present, read the import before importing again.", "request_id": "req_example" } } } } } } }, "get": { "operationId": "listAgreementPriceImports", "summary": "List price imports", "description": "Newest first, including failed and cancelled imports.", "tags": ["Agreement price imports"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of price imports.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementPriceImport" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/price-imports/{import_id}": { "get": { "operationId": "getAgreementPriceImport", "summary": "Get a price import", "tags": ["Agreement price imports"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "import_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The price import.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementPriceImport" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/price-imports/{import_id}/download": { "get": { "operationId": "downloadAgreementPriceImport", "summary": "Download the extracted price table", "description": "Signs a five-minute link to the CSV of every row the import extracted, in extraction order and as extracted, with two added columns: outcome (created, duplicate or invalid) and reason (the matching price or row for a duplicate, the broken price rules for an invalid row). It exists once the import completes and is deleted with its Document.", "tags": ["Agreement price imports"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "import_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A signed download link.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": ["download_url", "expires_at"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The import has not completed, so it has no price table.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The import has not completed, so it has no price table.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/documents": { "get": { "operationId": "listAgreementDocuments", "summary": "List agreement documents", "description": "Ordered by position then Document UUID, unknown positions last. Read access includes metadata for linked Documents.", "tags": ["Agreement documents"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Document relationships.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementDocument" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "linkAgreementDocument", "summary": "Link an existing Document", "description": "Requires Write access, as does uploading new bytes. Checks organization ownership and R2 bytes and clears a pending-upload marker when present. A new link starts ingestion in the background: the file type, page count and deterministic content are read from the bytes and recorded on the Document. No extraction run or classification is started. Positions start at zero and default to appending. Identical repeated links return 200; different attributes return 409.", "tags": ["Agreement documents"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": ["terms", "price_list", "uncategorized", "excluded"], "default": "uncategorized" }, "position": { "type": "integer", "minimum": 0, "maximum": 2147483647 } }, "required": ["document_id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementDocument" } } } }, "201": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementDocument" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/documents/{document_id}": { "get": { "operationId": "getAgreementDocument", "summary": "Get an agreement document relationship", "tags": ["Agreement documents"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "document_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementDocument" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateAgreementDocument", "summary": "Edit document role or position", "tags": ["Agreement documents"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "document_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412." }, "required": false, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["terms", "price_list", "uncategorized", "excluded"] }, "position": { "type": ["integer", "null"], "minimum": 0, "maximum": 2147483647 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementDocument" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "unlinkAgreementDocument", "summary": "Unlink an agreement document", "description": "Removes only the relationship. Retains the shared Document, prior link/chunk evidence, and existing assessment provenance.", "tags": ["Agreement documents"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "document_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412." }, "required": false, "description": "Optional strong ETag from the individual resource GET. A stale validator returns 412.", "name": "if-match", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Document unlinked." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Work is in progress, active-agreement requirements are unmet, the source is unavailable, or an idempotency key conflicts.", "request_id": "req_example" } } } } }, "412": { "description": "The resource changed since the supplied ETag was read.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_precondition_failed" }, "example": { "error": { "code": "precondition_failed", "message": "The resource changed since the supplied ETag was read.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/documents/{document_id}/classify": { "post": { "operationId": "classifyAgreementDocument", "summary": "Suggest an agreement document role", "description": "Classifies one attached PDF of at most 50 MiB using a preview of at most 10 pages and 60,000 characters, with a bounded visual preview for scans. Returns a suggested terms, price_list or excluded role, reason and optional price-import context in the workflow item result. An unusable preview produces a skipped item with role null. Does not require or start extraction, apply a role, or import prices.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "document_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "202": { "description": "Suggestion admitted or equivalent request already active. Poll the workflow and read its item result. Failed or cancelled requests can be retried by repeating this POST.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id", "workflow_run_item_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The admitted run ended concurrently. Inspect workflow_run_id when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The admitted run ended concurrently. Inspect workflow_run_id when provided.", "request_id": "req_example" } } } } }, "415": { "description": "Only declared application/pdf Documents are supported. Filename extensions do not override the MIME type.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_unsupported_media_type" }, "example": { "error": { "code": "unsupported_media_type", "message": "Only declared application/pdf Documents are supported. Filename extensions do not override the MIME type.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or dispatch was not confirmed. Inspect workflow_run_id before retrying when provided. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": false, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or dispatch was not confirmed. Inspect workflow_run_id before retrying when provided. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/suggest-details": { "post": { "operationId": "suggestAgreementDetails", "summary": "Suggest agreement details", "description": "Reads 1–10 distinct attached PDFs with the stored terms role, totaling at most 50 MiB. Other document roles return 400 validation_error. Uses published Markdown when available, otherwise the original PDF; extraction is not required or started. The server supplies either format to the model using its configured file transport. Either extraction strategy is accepted, regardless of verification outcome. Extracted Markdown is limited to 500,000 combined UTF-8 bytes; each original PDF supplied directly is limited to 15 MB (15,000,000 bytes). The job reads every selected file and fails clearly at model limits without truncation. Returns proposed fields, extracted parties and canonical mappings using shared match-or-create resolution. Does not apply values or enable matching. Review and apply chosen values through ordinary PATCH with If-Match. Subsequent document changes do not invalidate completed results. Selected files must remain available until processing finishes.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 10 } }, "required": ["document_ids"], "additionalProperties": false } } } }, "responses": { "202": { "description": "Suggestion admitted or equivalent request already active. Poll the workflow and read its item result. Failed or cancelled requests can be retried by repeating this POST.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id", "workflow_run_item_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Different suggestion inputs are active or the admitted run ended concurrently. Inspect workflow_run_id when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Different suggestion inputs are active or the admitted run ended concurrently. Inspect workflow_run_id when provided.", "request_id": "req_example" } } } } }, "415": { "description": "Only declared application/pdf Documents are supported. Filename extensions do not override the MIME type.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_unsupported_media_type" }, "example": { "error": { "code": "unsupported_media_type", "message": "Only declared application/pdf Documents are supported. Filename extensions do not override the MIME type.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or dispatch was not confirmed. Inspect workflow_run_id before retrying when provided. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": false, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or dispatch was not confirmed. Inspect workflow_run_id before retrying when provided. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/context-suggestions": { "get": { "operationId": "listAgreementContextSuggestions", "summary": "List suggested instruction edits", "description": "Pending edits to the agreement's instructions, proposed from alert dismissals that carried a category or note. Only suggestions that still apply to the current instructions are returned, ordered by where they apply, with appends last. Suggestions whose anchor an edit removed are deleted, so every returned suggestion still anchors exactly once in the current instructions. New suggestions arrive through agreement_context_suggestions workflow runs; list them with GET /v1/workflow-runs?type=agreement_context_suggestions&resource_type=agreement&resource_id={id}.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Every pending suggestion that applies to the current instructions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContextSuggestion" } } }, "required": ["data"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/context-suggestions/{suggestion_id}/accept": { "post": { "operationId": "acceptAgreementContextSuggestion", "summary": "Accept a suggested instruction edit", "description": "Applies the edit to the agreement's instructions as an ordinary edit: the same 20,000-character limit and in-progress rules as PATCH apply, and the agreement version advances, so existing checks become outdated. Other pending suggestions the edit no longer fits are deleted. Returns the updated agreement and its new ETag.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "A pending suggestion of this agreement." }, "required": true, "description": "A pending suggestion of this agreement.", "name": "suggestion_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "ETag": { "schema": { "type": "string", "description": "Strong validator for this individual resource." }, "required": true, "description": "Strong validator for this individual resource." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The suggestion was already reviewed, no longer matches the instructions, would make them longer than 20,000 characters, or agreement work is in progress. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The suggestion was already reviewed, no longer matches the instructions, would make them longer than 20,000 characters, or agreement work is in progress. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/agreements/{id}/context-suggestions/{suggestion_id}/reject": { "post": { "operationId": "rejectAgreementContextSuggestion", "summary": "Reject a suggested instruction edit", "description": "Marks the suggestion rejected without changing the instructions. Later suggestion runs for the agreement see the rejected edit, so they propose it again only with new evidence.", "tags": ["Agreements"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "A pending suggestion of this agreement." }, "required": true, "description": "A pending suggestion of this agreement.", "name": "suggestion_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Suggestion rejected." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The suggestion was already reviewed. Nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The suggestion was already reviewed. Nothing changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/documents": { "get": { "operationId": "listDocuments", "summary": "List Documents and unattached uploads", "tags": ["Documents"], "description": "Lists owned Document metadata without storage requests. Upload placeholders may not yet have bytes. Filter category=invoice and unattached=true for uploads with no retained relationship. Independent flags distinguish submitted import sources, later invoice attachments and historical versions. previous_version_id selects immediate successors; follow these relationships with normal pagination. File size and page count sorting covers the full selection.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": ["invoice", "agreement", "other"] }, "required": false, "name": "category", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "unattached", "in": "query" }, { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "file_name", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "previous_version_id", "in": "query" }, { "schema": { "type": "string", "enum": ["created_at", "file_name", "file_size", "page_count"], "default": "created_at" }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "required": false, "name": "order", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Live cursor page of Documents.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "category": { "type": ["string", "null"], "enum": ["invoice", "agreement", "other", null] }, "provenance": { "type": "object", "properties": { "uploader": { "type": ["object", "null"], "properties": { "user_id": { "type": "string" }, "name": { "type": ["string", "null"] } }, "required": ["user_id", "name"] }, "api_key": { "type": ["object", "null"], "properties": { "name": { "type": "string" } }, "required": ["name"] }, "email": { "type": ["object", "null"], "properties": { "sender": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] } }, "required": ["sender", "name"] }, "integration": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["id", "name", "type"] } }, "required": ["uploader", "api_key", "email", "integration"] }, "submitted_source": { "type": "boolean" }, "invoice_attachment": { "type": "boolean" }, "historical_version": { "type": "boolean" } }, "required": [ "document", "category", "provenance", "submitted_source", "invoice_attachment", "historical_version" ] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/documents/upload": { "post": { "operationId": "uploadDocument", "summary": "Authorize a document upload", "tags": ["Documents"], "description": "Creates a Document placeholder and a short-lived upload capability. PUT the bytes directly to upload_url with all returned headers before expires_at. Then pass document_id to an invoice import, invoice attachment, or agreement document link; there is no upload completion endpoint.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "enum": ["invoice", "agreement", "other"] }, "file_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "mime_type": { "type": "string", "maxLength": 255, "pattern": "^[a-z0-9!#$&^_.+-]+\\/[a-z0-9!#$&^_.+-]+$" }, "file_size": { "type": "integer", "minimum": 100, "maximum": 52428800 } }, "required": ["file_name", "mime_type", "file_size"], "additionalProperties": false }, "example": { "file_name": "invoice-2026-001.pdf", "mime_type": "application/pdf", "file_size": 48321 } } } }, "responses": { "201": { "description": "Document ID and scoped upload URL, required headers, and expiration.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid" }, "upload_url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" } }, "required": ["document_id", "upload_url", "headers", "expires_at"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication or upload signing is temporarily unavailable. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication or upload signing is temporarily unavailable. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/documents/upload/batch": { "post": { "operationId": "uploadDocumentsBatch", "summary": "Authorize a batch of document uploads", "tags": ["Documents"], "description": "Accepts metadata for 1–100 files. Returns Document IDs, upload URLs, required headers and expiry in request order. The whole request is validated and all placeholders are created in one transaction. PUT each file directly to its upload_url before expires_at; no completion endpoint is needed. This creates new Documents on each request, just like single upload preparation.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": ["invoice", "agreement", "other"] }, "file_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "mime_type": { "type": "string", "maxLength": 255, "pattern": "^[a-z0-9!#$&^_.+-]+\\/[a-z0-9!#$&^_.+-]+$" }, "file_size": { "type": "integer", "minimum": 100, "maximum": 52428800 } }, "required": ["file_name", "mime_type", "file_size"], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": ["entries"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Upload capabilities in request order.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid" }, "upload_url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" } }, "required": ["document_id", "upload_url", "headers", "expires_at"] }, "minItems": 1, "maxItems": 100 } }, "required": ["entries"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Upload signing is temporarily unavailable.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Upload signing is temporarily unavailable.", "request_id": "req_example" } } } } } } } }, "/v1/documents/{id}": { "get": { "operationId": "getDocument", "summary": "Get document metadata", "tags": ["Documents"], "description": "Returns organization-owned Document metadata. A placeholder can exist before its bytes are uploaded.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Document metadata.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/documents/{id}/download": { "get": { "operationId": "downloadDocument", "summary": "Authorize a document download", "tags": ["Documents"], "description": "Checks document ownership and object existence before returning a short-lived URL. Fetch the bytes directly from download_url before expires_at.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Authorized download URL and expiration.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": ["download_url", "expires_at"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/documents/{id}/content": { "get": { "operationId": "getDocumentContent", "summary": "Get Document content", "tags": ["Documents"], "description": "Returns usable content independently of resource links. A Document keeps one Markdown content per strategy; strategy selects it, whatever converter version produced it. A CSV, TSV or plain-text file is its own content: the response has origin original, the file type as content_type and a URL to the stored bytes, with no strategy or verification. Reads never start extraction or extend unlinked-upload retention. URLs expire in five minutes. Verification may be skipped or fail while content remains usable.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": ["datalab", "deterministic"], "description": "Omit for datalab content when it exists, otherwise deterministic." }, "required": false, "description": "Omit for datalab content when it exists, otherwise deterministic.", "name": "strategy", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Short-lived download URL. Extracted content adds its source version, producing strategy and verification summary.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "source_version": { "type": "string" }, "strategy": { "type": "string", "enum": ["datalab", "deterministic"] }, "verification": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["verified", "skipped", "error"] }, "reason": { "type": ["string", "null"], "maxLength": 100 }, "issue_count": { "type": "integer", "minimum": 0 }, "dropped_correction_count": { "type": "integer", "minimum": 0 } }, "required": [ "outcome", "reason", "issue_count", "dropped_correction_count" ] }, "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "content_type": { "type": "string", "enum": ["text/markdown"] }, "origin": { "type": "string", "enum": ["extracted"] } }, "required": [ "source_version", "strategy", "verification", "download_url", "expires_at", "content_type", "origin" ] }, { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "content_type": { "type": "string", "enum": ["text/csv", "text/tab-separated-values", "text/plain"] }, "origin": { "type": "string", "enum": ["original"] } }, "required": ["download_url", "expires_at", "content_type", "origin"] } ] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Current content is unavailable or the original source is missing/changed. Start extraction explicitly for content_not_ready.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_content_not_ready_source_unavailable" }, "example": { "error": { "code": "content_not_ready", "message": "Current content is unavailable or the original source is missing/changed. Start extraction explicitly for content_not_ready.", "request_id": "req_example" } } } } }, "415": { "description": "Supports PDF, DOCX, XLSX, EML, MSG, PNG and JPEG declarations. Unsupported MIME types, including text, Markdown and legacy Office formats, are rejected; filenames do not override declarations.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_unsupported_media_type" }, "example": { "error": { "code": "unsupported_media_type", "message": "Supports PDF, DOCX, XLSX, EML, MSG, PNG and JPEG declarations. Unsupported MIME types, including text, Markdown and legacy Office formats, are rejected; filenames do not override declarations.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/documents/{id}/extract": { "post": { "operationId": "extractDocument", "summary": "Extract Document content", "tags": ["Documents"], "description": "Extracts an organization-owned PDF, DOCX, XLSX, EML, MSG, PNG or JPEG. PDF and DOCX support datalab and deterministic; XLSX, EML and MSG support deterministic; PNG/JPEG support datalab. Defaults are datalab for PDF/images and deterministic otherwise. Optional fallback_strategy runs once only when the primary produces no extractable content. Incomplete content, malformed files, limits, cancellation and provider errors never trigger fallback. Content is kept per strategy and reused whatever converter version produced it, so a newer version never re-extracts a Document by itself. A fallback is reused only after the requested strategy found no extractable content. Equivalent active work is shared. A different active strategy or fallback policy returns 409 with workflow_run_id. A new strategy adds content and never replaces content from another strategy. Failed/cancelled work can be retried as a linked new run. Does not extend unlinked-upload retention.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "strategy": { "type": "string", "enum": ["datalab", "deterministic"], "description": "Omit for the MIME default: datalab for PDF, PNG and JPEG; deterministic for DOCX, XLSX, EML, MSG and HTML." }, "fallback_strategy": { "type": "string", "enum": ["datalab", "deterministic"], "description": "Optional distinct strategy supported by this MIME. Invoked once only on no extractable content. Omit for no fallback." } }, "additionalProperties": false }, "examples": { "datalab": { "summary": "OCR and table reconstruction (default for PDF/images)", "value": { "strategy": "datalab" } }, "fallback": { "summary": "Native DOCX or PDF with explicit OCR fallback", "value": { "strategy": "deterministic", "fallback_strategy": "datalab" } }, "deterministic": { "summary": "Embedded text without provider calls", "value": { "strategy": "deterministic" } } } } } }, "responses": { "200": { "description": "Usable content for the request already exists. GET content_url to retrieve its descriptor and download URL.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ready"] }, "content_url": { "type": "string", "description": "Relative API URL to retrieve the current content descriptor." } }, "required": ["status", "content_url"] }, "example": { "status": "ready", "content_url": "/v1/documents/550e8400-e29b-41d4-a716-446655440000/content?strategy=datalab" } } } }, "202": { "description": "Extraction admitted or equivalent work already active. Poll the workflow run.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" } }, "required": ["workflow_run_id", "workflow_run_item_id"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "A different extraction is active, the source is unavailable, or the admitted run ended concurrently. workflow_run_id identifies conflicting work when available.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_extraction_in_progress_source_unavailable_conflict" }, "example": { "error": { "code": "extraction_in_progress", "message": "A different extraction is active, the source is unavailable, or the admitted run ended concurrently. workflow_run_id identifies conflicting work when available.", "request_id": "req_example" } } } } }, "415": { "description": "Supports PDF, DOCX, XLSX, EML, MSG, PNG and JPEG declarations. Unsupported MIME types, including text, Markdown and legacy Office formats, are rejected; filenames do not override declarations.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_unsupported_media_type" }, "example": { "error": { "code": "unsupported_media_type", "message": "Supports PDF, DOCX, XLSX, EML, MSG, PNG and JPEG declarations. Unsupported MIME types, including text, Markdown and legacy Office formats, are rejected; filenames do not override declarations.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited, or extraction dispatch failed or was not confirmed. Inspect workflow_run_id before retrying when provided. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited, or extraction dispatch failed or was not confirmed. Inspect workflow_run_id before retrying when provided. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/imports/batch": { "post": { "operationId": "createInvoiceImportBatch", "summary": "Submit an invoice import batch", "tags": ["Invoice imports"], "description": "Submits one finite selection, at most 100 total source files and the API request body limit. Validates ownership before admission. The transaction records accepted work, source failures, duplicate skips and capacity skips in one closed workflow run. One finite provider batch is dispatched after commit; unconfirmed dispatch is retained for recovery. Idempotency-Key is required; replay returns original admission references without dispatching again. Poll workflow-run items for current status. No batch session is created.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": true, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "primary_document_id": { "type": "string", "format": "uuid", "description": "Document containing the invoice; its bytes must already be uploaded." }, "attachment_document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Distinct supplementary Documents in the order to retain; must exclude the primary Document." } }, "required": ["primary_document_id"], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": ["entries"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Idempotent replay; dispatch is null because current execution state must be read from the run.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "document_id": { "type": "string", "format": "uuid" }, "source_document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 }, "import_id": { "type": ["string", "null"], "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": ["accepted", "duplicate", "capacity_rejected", "failed"] }, "invoice_id": { "type": ["string", "null"], "format": "uuid" }, "failure": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"] }, "dispatch": { "type": ["string", "null"], "enum": ["accepted", "unconfirmed", "failed", "terminal", null] } }, "required": [ "index", "document_id", "source_document_ids", "import_id", "workflow_run_item_id", "outcome", "invoice_id", "failure", "dispatch" ] }, "maxItems": 100 } }, "required": ["workflow_run_id", "entries"] } } } }, "202": { "description": "Committed submission; inspect each entry and follow the workflow run.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "document_id": { "type": "string", "format": "uuid" }, "source_document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 }, "import_id": { "type": ["string", "null"], "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": ["accepted", "duplicate", "capacity_rejected", "failed"] }, "invoice_id": { "type": ["string", "null"], "format": "uuid" }, "failure": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"] }, "dispatch": { "type": ["string", "null"], "enum": ["accepted", "unconfirmed", "failed", "terminal", null] } }, "required": [ "index", "document_id", "source_document_ids", "import_id", "workflow_run_item_id", "outcome", "invoice_id", "failure", "dispatch" ] }, "maxItems": 100 } }, "required": ["workflow_run_id", "entries"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "Idempotency conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Idempotency conflict.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/imports/sources": { "get": { "operationId": "listInvoiceImportSources", "summary": "List submitted import sources", "tags": ["Invoice imports"], "description": "Lists distinct submitted Documents across up to 100 imports, with every selected import relationship. File size and page count ordering applies across the complete selection. Later invoice attachments are excluded. Cursors are live and bound to selection and sort.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "maxLength": 4000 }, "required": true, "name": "import_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["created_at", "file_name", "file_size", "page_count", "position"], "default": "created_at" }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "required": false, "name": "order", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Page of submitted sources.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "provenance": { "type": "object", "properties": { "uploader": { "type": ["object", "null"], "properties": { "user_id": { "type": "string" }, "name": { "type": ["string", "null"] } }, "required": ["user_id", "name"] }, "api_key": { "type": ["object", "null"], "properties": { "name": { "type": "string" } }, "required": ["name"] }, "email": { "type": ["object", "null"], "properties": { "sender": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] } }, "required": ["sender", "name"] }, "integration": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["id", "name", "type"] } }, "required": ["uploader", "api_key", "email", "integration"] }, "imports": { "type": "array", "items": { "type": "object", "properties": { "import_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": ["primary", "attachment"] }, "position": { "type": "integer" } }, "required": ["import_id", "role", "position"] }, "maxItems": 100 } }, "required": ["document", "provenance", "imports"] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/imports/retry": { "post": { "operationId": "retryInvoiceImports", "summary": "Retry selected failed imports", "tags": ["Invoice imports"], "description": "At most 100 targets. Deduplicates by import ID and verifies every selected file belongs to its import. Each target has an independent transaction and idempotency receipt derived from the required request key. expected_item_id prevents retrying a newer execution. Retry all traverses the normal failed import list using created_at ascending; leaving the client page stops further submissions, while admitted work continues.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": true, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "import_id": { "type": "string", "format": "uuid" }, "expected_item_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" } }, "required": ["import_id", "expected_item_id"], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": ["targets"], "additionalProperties": false } } } }, "responses": { "200": { "description": "One result per distinct import.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "import_id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": ["accepted", "blocked", "failure"] }, "workflow_run_id": { "type": ["string", "null"], "format": "uuid" }, "workflow_run_item_id": { "type": ["string", "null"], "format": "uuid" }, "dispatch": { "type": ["string", "null"], "enum": ["accepted", "failed", "unconfirmed", "terminal", null] }, "failure": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"] } }, "required": [ "import_id", "outcome", "workflow_run_id", "workflow_run_item_id", "dispatch", "failure" ] }, "maxItems": 100 } }, "required": ["results"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/imports/remove": { "post": { "operationId": "removeInvoiceImportFiles", "summary": "Remove selected imports or files", "tags": ["Invoice imports"], "description": "At most 100 independent targets. Terminal imports are soft-deleted from history. Invoice attachments use the existing unlink command and claim/primary protections. Truly unattached Documents are removed with retained-byte cleanup. Imported sources, evidence and versions remain protected; no command deletes a published invoice.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_import"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["document"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_attachment"] }, "id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" } }, "required": ["type", "id", "invoice_id"], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 100 } }, "required": ["targets"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Independent target outcomes.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_import"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["document"] }, "id": { "type": "string", "format": "uuid" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice_attachment"] }, "id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" } }, "required": ["type", "id", "invoice_id"], "additionalProperties": false } ] }, "outcome": { "type": "string", "enum": ["success", "blocked", "failure"] }, "failure": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["target", "outcome", "failure"] }, "maxItems": 100 } }, "required": ["results"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/imports/{id}": { "delete": { "operationId": "deleteInvoiceImport", "summary": "Remove a terminal import from history", "tags": ["Invoice imports"], "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Import removed from ordinary history; sources and published invoices retained.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [true] } }, "required": ["deleted"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Cancel active imports first.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Cancel active imports first.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "get": { "operationId": "getInvoiceImport", "summary": "Get an invoice import", "tags": ["Invoice imports"], "description": "Returns current processing status, ordered sources, extraction evidence, and any resulting invoice. A completed import can have imported, duplicate, or not_invoice as its outcome; imported does not imply financial validity.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Import status, sources, and bounded extraction evidence.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceImport" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/imports": { "post": { "operationId": "createInvoiceImport", "summary": "Import an invoice from Documents", "tags": ["Invoice imports"], "description": "Admits one primary Document and distinct, ordered attachments (100 bytes minimum per file; 50 MiB primary, 25 MiB per attachment; no attachment-count or combined-size cap) after their bytes have been uploaded. A known primary-file duplicate returns the existing invoice without starting work. The same business-identity guard used by structured creation checks extracted invoice fields before publication; a match completes as duplicate. Idempotency-Key is optional and protects request retries. New admissions reserve capacity and return 202 only after execution acceptance is confirmed. PDF imports use model extraction. Primary XML must be PEPPOL BIS Billing 3.0 UBL Invoice or CreditNote; unsupported XML fails during processing without model fallback. Usable extraction can publish a financially invalid invoice. A replay returns the original admission reference without starting or redispatching work; read the import for current status.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "primary_document_id": { "type": "string", "format": "uuid", "description": "Document containing the invoice; its bytes must already be uploaded." }, "attachment_document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Distinct supplementary Documents in the order to retain; must exclude the primary Document." } }, "required": ["primary_document_id"], "additionalProperties": false }, "example": { "primary_document_id": "11111111-1111-4111-8111-111111111111", "attachment_document_ids": ["22222222-2222-4222-8222-222222222222"] } } } }, "responses": { "200": { "description": "Idempotent replay or known primary-file duplicate", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["accepted"] }, "import_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" } }, "required": [ "outcome", "import_id", "workflow_run_id", "workflow_run_item_id" ] }, { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["duplicate"] }, "invoice_id": { "type": "string", "format": "uuid" } }, "required": ["outcome", "invoice_id"] } ] }, "example": { "outcome": "duplicate", "invoice_id": "55555555-5555-4555-8555-555555555555" } } } }, "202": { "description": "Accepted for asynchronous processing", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["accepted"] }, "import_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" } }, "required": ["outcome", "import_id", "workflow_run_id", "workflow_run_item_id"] }, "example": { "outcome": "accepted", "import_id": "33333333-3333-4333-8333-333333333333", "workflow_run_id": "44444444-4444-4444-8444-444444444444", "workflow_run_item_id": "66666666-6666-4666-8666-666666666666" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "Conflicting idempotency key or permanently deleted replay target, unavailable capacity, incompatible import state, or source already in use. source_unavailable means source bytes are missing or changed; inspect error.code. An execution conflict after admission includes import_id.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Conflicting idempotency key or permanently deleted replay target, unavailable capacity, incompatible import state, or source already in use. source_unavailable means source bytes are missing or changed; inspect error.code. An execution conflict after admission includes import_id.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication or admission is temporarily unavailable, or execution acceptance could not be confirmed. When error.import_id and Location are present, the import is retained: read its status before an explicit retry. Replaying the same key does not redispatch work.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication or admission is temporarily unavailable, or execution acceptance could not be confirmed. When error.import_id and Location are present, the import is retained: read its status before an explicit retry. Replaying the same key does not redispatch work.", "request_id": "req_example" } } } } } } }, "get": { "operationId": "listInvoiceImports", "summary": "List invoice imports", "tags": ["Invoice imports"], "description": "Lists processing attempts by import, optionally filtered by current status. has_ingestion is organization-wide and independent of filters or pagination, including retained legacy invoices and invoice Documents. For onboarding after an empty invoice list, request limit=1; an empty Import page alone does not prove nothing was uploaded.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "maxLength": 4000 }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "maxLength": 4000 }, "required": false, "name": "outcome", "in": "query" }, { "schema": { "type": "string", "maxLength": 4000, "description": "How the source entered: upload, api, email or integration." }, "required": false, "description": "How the source entered: upload, api, email or integration.", "name": "origin", "in": "query" }, { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "file_name", "in": "query" }, { "schema": { "type": "string", "maxLength": 27, "format": "date-time" }, "required": false, "name": "created_from", "in": "query" }, { "schema": { "type": "string", "maxLength": 27, "format": "date-time" }, "required": false, "name": "created_before", "in": "query" }, { "schema": { "type": "string", "enum": ["created_at", "updated_at", "primary_file_name"], "default": "created_at" }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "required": false, "name": "order", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": "false" }, "required": false, "name": "deleted", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of import summaries; next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceImportSummary" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] }, "total": { "type": "integer" }, "failed_retryable_count": { "type": "integer" }, "has_ingestion": { "type": "boolean", "description": "Organization-wide presence of retained Imports, invoice rows of any status (including deleted legacy rows), or invoice-category Documents. Independent of status filters and pagination. An empty data page can still have has_ingestion=true. Permanent removal of all evidence cannot prove past uploads." } }, "required": [ "data", "next_cursor", "total", "failed_retryable_count", "has_ingestion" ] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/imports/{id}/cancel": { "post": { "operationId": "cancelInvoiceImport", "summary": "Cancel an invoice import", "tags": ["Invoice imports"], "description": "Commits cancellation before requesting execution cancellation. Repeated cancellation succeeds; completed and failed imports cannot be cancelled.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Cancelled import with its retained sources and evidence.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceImport" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Only queued, running, or already cancelled imports can be cancelled.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Only queued, running, or already cancelled imports can be cancelled.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/imports/{id}/retry": { "post": { "operationId": "retryInvoiceImport", "summary": "Retry an invoice import", "tags": ["Invoice imports"], "description": "Requires a failed or cancelled import and available, unchanged sources. Creates a new current run and reserves capacity. A replay returns the original retry execution without starting or redispatching work; read the import for current status.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Idempotent replay of the original retry execution", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["accepted"] }, "import_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" } }, "required": ["outcome", "import_id", "workflow_run_id", "workflow_run_item_id"] } } } }, "202": { "description": "Accepted for asynchronous processing", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["accepted"] }, "import_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "workflow_run_item_id": { "type": "string", "format": "uuid" } }, "required": ["outcome", "import_id", "workflow_run_id", "workflow_run_item_id"] }, "example": { "outcome": "accepted", "import_id": "33333333-3333-4333-8333-333333333333", "workflow_run_id": "44444444-4444-4444-8444-444444444444", "workflow_run_item_id": "66666666-6666-4666-8666-666666666666" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Conflicting idempotency key or permanently deleted replay target, unavailable capacity, incompatible import state, or source already in use. source_unavailable means source bytes are missing or changed; inspect error.code. An execution conflict after admission includes import_id.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "Conflicting idempotency key or permanently deleted replay target, unavailable capacity, incompatible import state, or source already in use. source_unavailable means source bytes are missing or changed; inspect error.code. An execution conflict after admission includes import_id.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication or admission is temporarily unavailable, or execution acceptance could not be confirmed. When error.import_id and Location are present, the import is retained: read its status before an explicit retry. Replaying the same key does not redispatch work.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication or admission is temporarily unavailable, or execution acceptance could not be confirmed. When error.import_id and Location are present, the import is retained: read its status before an explicit retry. Replaying the same key does not redispatch work.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/facets": { "get": { "operationId": "listInvoiceFacetValues", "summary": "List invoice facet values", "tags": ["Invoices"], "description": "Distinct values from visible completed invoices, ordered by value. reference combines scalar invoice-reference fields; include_order_references adds exact-match array elements. Omit that option for substring operators. delivery_address includes the address component fields.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "reference", "buyer_reference", "seller_reference", "order_reference", "delivery_address" ] }, "required": true, "name": "field", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": false }, "required": false, "name": "include_order_references", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Bounded facet suggestions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" } }, "required": ["value"] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/export": { "get": { "operationId": "exportInvoices", "summary": "Export selected invoices as CSV", "tags": ["Invoices"], "description": "Streams the complete selection using the same filters as list/metrics. Summary rows traverse invoice UUID ascending; line rows traverse invoice UUID, line number and line UUID. Does not accept list cursors or sorting. Live traversal reapplies filters and team definitions per batch: concurrent changes may move records into or out of later batches, and the export is not a snapshot. Invoice-items emits one row per stored line (invoices without lines contribute no rows). Exact decimals, blank nulls, JSON arrays, UTF-8 BOM, CRLF and formula-safe text. Empty selections contain the header. Failures after streaming starts terminate the download; retry starts a fresh export. No saved file or byte-range resume. Use parseAs: stream with the generated client.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match on invoice number or title." }, "required": false, "description": "Case-insensitive substring match on invoice number or title.", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "Match any canonical supplier UUID or literal null for no supplier. Maximum 50 comma-separated values; omit for all suppliers. Empty entries are invalid." }, "required": false, "description": "Match any canonical supplier UUID or literal null for no supplier. Maximum 50 comma-separated values; omit for all suppliers. Empty entries are invalid.", "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match any canonical recipient UUID or literal null for no recipient. Maximum 50 comma-separated values; omit for all recipients. Empty entries are invalid." }, "required": false, "description": "Match any canonical recipient UUID or literal null for no recipient. Maximum 50 comma-separated values; omit for all recipients. Empty entries are invalid.", "name": "recipient_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match any listed category: invoice, credit_note, self_billed_invoice. Maximum 50 comma-separated values; omit for all categories." }, "required": false, "description": "Match any listed category: invoice, credit_note, self_billed_invoice. Maximum 50 comma-separated values; omit for all categories.", "name": "categories", "in": "query" }, { "schema": { "type": "string", "description": "Match any three-letter currency code (case-insensitive), or literal null for unknown currency. Maximum 50 comma-separated values; omit for all currencies. Example: NOK,EUR,null." }, "required": false, "description": "Match any three-letter currency code (case-insensitive), or literal null for unknown currency. Maximum 50 comma-separated values; omit for all currencies. Example: NOK,EUR,null.", "name": "currency_codes", "in": "query" }, { "schema": { "type": "string", "enum": ["and", "or"], "default": "and", "description": "and requires every supplied column filter; or requires at least one. Both bounds within each date range must match, and that range is one group member. Organization, published/deleted state, search, agreement_ids and mine/team scope are always required outside the group. No column filters means no group restriction." }, "required": false, "description": "and requires every supplied column filter; or requires at least one. Both bounds within each date range must match, and that range is one group member. Organization, published/deleted state, search, agreement_ids and mine/team scope are always required outside the group. No column filters means no group restriction.", "name": "join_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to supplier_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to supplier_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "supplier_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to recipient_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to recipient_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "recipient_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to categories: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to categories: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "category_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to currency_codes: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to currency_codes: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "currency_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to confidence_levels: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to confidence_levels: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "confidence_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to check_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to check_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "check_status_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to alert_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to alert_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "alert_status_operator", "in": "query" }, { "schema": { "type": "string", "description": "Combined alert status, in precedence order: credited (fully financially covered by credit notes), checking (active checks), has_issues (pending or claimed alerts), clean (completed coverage without open alerts), not_checked (all remaining coverage). Uses alert_scope. Comma-separated, maximum 50; omit for all states." }, "required": false, "description": "Combined alert status, in precedence order: credited (fully financially covered by credit notes), checking (active checks), has_issues (pending or claimed alerts), clean (completed coverage without open alerts), not_checked (all remaining coverage). Uses alert_scope. Comma-separated, maximum 50; omit for all states.", "name": "alert_statuses", "in": "query" }, { "schema": { "type": "string", "description": "Original extraction confidence: high, mid, low or unknown. Both successful creating-import stages must retain confidence assessments and stage fingerprints; publication validates their respective cache keys. The lower level wins. Structured/XML creation and unavailable history are unknown. Comma-separated, maximum 50; omit for all levels." }, "required": false, "description": "Original extraction confidence: high, mid, low or unknown. Both successful creating-import stages must retain confidence assessments and stage fingerprints; publication validates their respective cache keys. The lower level wins. Structured/XML creation and unavailable history are unknown. Comma-separated, maximum 50; omit for all levels.", "name": "confidence_levels", "in": "query" }, { "schema": { "type": "string", "description": "Canonical check coverage in alert_scope: not_checkable (credit note or recorded credit-note match), checking (active work), not_checked (no check recorded), completed (all current matches checked), incomplete (missing, failed, cancelled, outdated or unknown coverage). Comma-separated, maximum 50; omit for all states." }, "required": false, "description": "Canonical check coverage in alert_scope: not_checkable (credit note or recorded credit-note match), checking (active work), not_checked (no check recorded), completed (all current matches checked), incomplete (missing, failed, cancelled, outdated or unknown coverage). Comma-separated, maximum 50; omit for all states.", "name": "check_statuses", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires at least one recorded credit-note relationship; false selects zero. For invoice/self_billed_invoice this means linked credit notes; for credit_note this means matched invoices. Includes retained links to soft-deleted counterparts. Does not establish financial resolution. Omit for either." }, "required": false, "description": "true requires at least one recorded credit-note relationship; false selects zero. For invoice/self_billed_invoice this means linked credit notes; for credit_note this means matched invoices. Includes retained links to soft-deleted counterparts. Does not establish financial resolution. Omit for either.", "name": "has_recorded_match", "in": "query" }, { "schema": { "type": "string", "enum": ["invoice", "selected_agreements"], "default": "invoice", "description": "Selected scope requires agreement_ids and evaluates only currently matched selected agreements. Applies to checks, alert counts, filters and metrics." }, "required": false, "description": "Selected scope requires agreement_ids and evaluates only currently matched selected agreements. Applies to checks, alert counts, filters and metrics.", "name": "alert_scope", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Earliest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Earliest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "issued_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Latest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Latest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "issued_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Earliest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Earliest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "due_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Latest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Latest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "due_through", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Filter by deterministic financial validation, independent of extraction confidence or human approval." }, "required": false, "description": "Filter by deterministic financial validation, independent of extraction confidence or human approval.", "name": "financially_valid", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Filter by explicit human extraction confirmation. Does not change confidence or financial validity." }, "required": false, "description": "Filter by explicit human extraction confirmation. Does not change confidence or financial validity.", "name": "extraction_confirmed", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true selects unconfirmed low/mid extraction confidence, unmatched credit notes, or financially invalid invoices. false selects the exact complement. Always combines with the other selection using AND. Unknown confidence alone does not recommend review." }, "required": false, "description": "true selects unconfirmed low/mid extraction confidence, unmatched credit notes, or financially invalid invoices. false selects the exact complement. Always combines with the other selection using AND. Unknown confidence alone does not recommend review.", "name": "review_recommended", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated agreement IDs (maximum 50). Select invoices matched to any listed agreement in the target organization, regardless of agreement status. Unknown, deleted, or foreign agreements contribute no matches. Combines with other filters using AND; invoices are returned and counted once even if matched to several selected agreements." }, "required": false, "description": "Comma-separated agreement IDs (maximum 50). Select invoices matched to any listed agreement in the target organization, regardless of agreement status. Unknown, deleted, or foreign agreements contribute no matches. Combines with other filters using AND; invoices are returned and counted once even if matched to several selected agreements.", "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires at least one current organization-owned, nondeleted agreement match; false requires none. Omit for either. Independent of credit-note matching and completed checks." }, "required": false, "description": "true requires at least one current organization-owned, nondeleted agreement match; false requires none. Omit for either. Independent of credit-note matching and completed checks.", "name": "has_agreement_match", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true is equivalent to check_statuses=completed in alert_scope; false includes every other state. Omit for either." }, "required": false, "description": "true is equivalent to check_statuses=completed in alert_scope; false includes every other state. Omit for either.", "name": "alert_checked", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true excludes credit notes and invoices with recorded credit-note matches; false selects those excluded resources. Eligibility is invoice-wide even in selected-agreement scope. Omit for either." }, "required": false, "description": "true excludes credit notes and invoices with recorded credit-note matches; false selects those excluded resources. Eligibility is invoice-wide even in selected-agreement scope. Omit for either.", "name": "alert_checkable", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires retained pending or claimed alerts in alert_scope (including outdated findings); false requires none. No open alerts does not prove completed checks. Omit for either." }, "required": false, "description": "true requires retained pending or claimed alerts in alert_scope (including outdated findings); false requires none. No open alerts does not prove completed checks. Omit for either.", "name": "has_open_alerts", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": "false", "description": "false selects active invoices; true selects only soft-deleted invoices." }, "required": false, "description": "false selects active invoices; true selects only soft-deleted invoices.", "name": "deleted", "in": "query" }, { "schema": { "type": "string", "enum": ["invoice", "invoice-items"], "default": "invoice", "description": "invoice emits one row per selected invoice; invoice-items emits one row per stored line with invoice columns repeated. Invoices without lines contribute no invoice-items rows." }, "required": false, "description": "invoice emits one row per selected invoice; invoice-items emits one row per stored line with invoice columns repeated. Invoices without lines contribute no invoice-items rows.", "name": "granularity", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Streaming CSV download. Success requires reading the entire body; HTTP 200 alone does not establish completion.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "required": true }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": true } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/metrics": { "get": { "operationId": "getInvoiceMetrics", "summary": "Summarize invoices by currency", "tags": ["Invoices"], "description": "Uses the same filters as listInvoices. Use agreement_ids to summarize currently matched invoices; matches are deduplicated across the selected agreements. With one agreement and no other filters, total_count equals its relationships.invoice_match_count. Totals are exact decimal strings separated by currency, including a null group for unknown currency. A total is null if any contributing amount is unknown. Credit notes reduce spend. With no issue-date bounds, totals cover lifetime spend including future-dated and undated invoices; inclusive issued_from and issued_through select a reporting period such as the last 12 months. Organization-currency coverage amounts include VAT and use the invoice-date exchange rate (latest preceding observation), with direct/inverse pairs or triangulation through NOK. Missing conversion inputs make the affected total null; incomplete_invoice_count counts affected eligible invoices. Same-currency invoices require no rate or date. Organization currency defaults to NOK when unset. Does not run matching or compliance checks.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match on invoice number or title." }, "required": false, "description": "Case-insensitive substring match on invoice number or title.", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "Match any canonical supplier UUID or literal null for no supplier. Maximum 50 comma-separated values; omit for all suppliers. Empty entries are invalid." }, "required": false, "description": "Match any canonical supplier UUID or literal null for no supplier. Maximum 50 comma-separated values; omit for all suppliers. Empty entries are invalid.", "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match any canonical recipient UUID or literal null for no recipient. Maximum 50 comma-separated values; omit for all recipients. Empty entries are invalid." }, "required": false, "description": "Match any canonical recipient UUID or literal null for no recipient. Maximum 50 comma-separated values; omit for all recipients. Empty entries are invalid.", "name": "recipient_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match any listed category: invoice, credit_note, self_billed_invoice. Maximum 50 comma-separated values; omit for all categories." }, "required": false, "description": "Match any listed category: invoice, credit_note, self_billed_invoice. Maximum 50 comma-separated values; omit for all categories.", "name": "categories", "in": "query" }, { "schema": { "type": "string", "description": "Match any three-letter currency code (case-insensitive), or literal null for unknown currency. Maximum 50 comma-separated values; omit for all currencies. Example: NOK,EUR,null." }, "required": false, "description": "Match any three-letter currency code (case-insensitive), or literal null for unknown currency. Maximum 50 comma-separated values; omit for all currencies. Example: NOK,EUR,null.", "name": "currency_codes", "in": "query" }, { "schema": { "type": "string", "enum": ["and", "or"], "default": "and", "description": "and requires every supplied column filter; or requires at least one. Both bounds within each date range must match, and that range is one group member. Organization, published/deleted state, search, agreement_ids and mine/team scope are always required outside the group. No column filters means no group restriction." }, "required": false, "description": "and requires every supplied column filter; or requires at least one. Both bounds within each date range must match, and that range is one group member. Organization, published/deleted state, search, agreement_ids and mine/team scope are always required outside the group. No column filters means no group restriction.", "name": "join_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to supplier_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to supplier_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "supplier_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to recipient_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to recipient_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "recipient_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to categories: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to categories: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "category_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to currency_codes: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to currency_codes: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "currency_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to confidence_levels: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to confidence_levels: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "confidence_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to check_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to check_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "check_status_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to alert_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to alert_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "alert_status_operator", "in": "query" }, { "schema": { "type": "string", "description": "Combined alert status, in precedence order: credited (fully financially covered by credit notes), checking (active checks), has_issues (pending or claimed alerts), clean (completed coverage without open alerts), not_checked (all remaining coverage). Uses alert_scope. Comma-separated, maximum 50; omit for all states." }, "required": false, "description": "Combined alert status, in precedence order: credited (fully financially covered by credit notes), checking (active checks), has_issues (pending or claimed alerts), clean (completed coverage without open alerts), not_checked (all remaining coverage). Uses alert_scope. Comma-separated, maximum 50; omit for all states.", "name": "alert_statuses", "in": "query" }, { "schema": { "type": "string", "description": "Original extraction confidence: high, mid, low or unknown. Both successful creating-import stages must retain confidence assessments and stage fingerprints; publication validates their respective cache keys. The lower level wins. Structured/XML creation and unavailable history are unknown. Comma-separated, maximum 50; omit for all levels." }, "required": false, "description": "Original extraction confidence: high, mid, low or unknown. Both successful creating-import stages must retain confidence assessments and stage fingerprints; publication validates their respective cache keys. The lower level wins. Structured/XML creation and unavailable history are unknown. Comma-separated, maximum 50; omit for all levels.", "name": "confidence_levels", "in": "query" }, { "schema": { "type": "string", "description": "Canonical check coverage in alert_scope: not_checkable (credit note or recorded credit-note match), checking (active work), not_checked (no check recorded), completed (all current matches checked), incomplete (missing, failed, cancelled, outdated or unknown coverage). Comma-separated, maximum 50; omit for all states." }, "required": false, "description": "Canonical check coverage in alert_scope: not_checkable (credit note or recorded credit-note match), checking (active work), not_checked (no check recorded), completed (all current matches checked), incomplete (missing, failed, cancelled, outdated or unknown coverage). Comma-separated, maximum 50; omit for all states.", "name": "check_statuses", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires at least one recorded credit-note relationship; false selects zero. For invoice/self_billed_invoice this means linked credit notes; for credit_note this means matched invoices. Includes retained links to soft-deleted counterparts. Does not establish financial resolution. Omit for either." }, "required": false, "description": "true requires at least one recorded credit-note relationship; false selects zero. For invoice/self_billed_invoice this means linked credit notes; for credit_note this means matched invoices. Includes retained links to soft-deleted counterparts. Does not establish financial resolution. Omit for either.", "name": "has_recorded_match", "in": "query" }, { "schema": { "type": "string", "enum": ["invoice", "selected_agreements"], "default": "invoice", "description": "Selected scope requires agreement_ids and evaluates only currently matched selected agreements. Applies to checks, alert counts, filters and metrics." }, "required": false, "description": "Selected scope requires agreement_ids and evaluates only currently matched selected agreements. Applies to checks, alert counts, filters and metrics.", "name": "alert_scope", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Earliest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Earliest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "issued_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Latest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Latest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "issued_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Earliest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Earliest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "due_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Latest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Latest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "due_through", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Filter by deterministic financial validation, independent of extraction confidence or human approval." }, "required": false, "description": "Filter by deterministic financial validation, independent of extraction confidence or human approval.", "name": "financially_valid", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Filter by explicit human extraction confirmation. Does not change confidence or financial validity." }, "required": false, "description": "Filter by explicit human extraction confirmation. Does not change confidence or financial validity.", "name": "extraction_confirmed", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true selects unconfirmed low/mid extraction confidence, unmatched credit notes, or financially invalid invoices. false selects the exact complement. Always combines with the other selection using AND. Unknown confidence alone does not recommend review." }, "required": false, "description": "true selects unconfirmed low/mid extraction confidence, unmatched credit notes, or financially invalid invoices. false selects the exact complement. Always combines with the other selection using AND. Unknown confidence alone does not recommend review.", "name": "review_recommended", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated agreement IDs (maximum 50). Select invoices matched to any listed agreement in the target organization, regardless of agreement status. Unknown, deleted, or foreign agreements contribute no matches. Combines with other filters using AND; invoices are returned and counted once even if matched to several selected agreements." }, "required": false, "description": "Comma-separated agreement IDs (maximum 50). Select invoices matched to any listed agreement in the target organization, regardless of agreement status. Unknown, deleted, or foreign agreements contribute no matches. Combines with other filters using AND; invoices are returned and counted once even if matched to several selected agreements.", "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires at least one current organization-owned, nondeleted agreement match; false requires none. Omit for either. Independent of credit-note matching and completed checks." }, "required": false, "description": "true requires at least one current organization-owned, nondeleted agreement match; false requires none. Omit for either. Independent of credit-note matching and completed checks.", "name": "has_agreement_match", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true is equivalent to check_statuses=completed in alert_scope; false includes every other state. Omit for either." }, "required": false, "description": "true is equivalent to check_statuses=completed in alert_scope; false includes every other state. Omit for either.", "name": "alert_checked", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true excludes credit notes and invoices with recorded credit-note matches; false selects those excluded resources. Eligibility is invoice-wide even in selected-agreement scope. Omit for either." }, "required": false, "description": "true excludes credit notes and invoices with recorded credit-note matches; false selects those excluded resources. Eligibility is invoice-wide even in selected-agreement scope. Omit for either.", "name": "alert_checkable", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires retained pending or claimed alerts in alert_scope (including outdated findings); false requires none. No open alerts does not prove completed checks. Omit for either." }, "required": false, "description": "true requires retained pending or claimed alerts in alert_scope (including outdated findings); false requires none. No open alerts does not prove completed checks. Omit for either.", "name": "has_open_alerts", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": "false", "description": "false selects active invoices; true selects only soft-deleted invoices." }, "required": false, "description": "false selects active invoices; true selects only soft-deleted invoices.", "name": "deleted", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Invoice counts, financially invalid count, and monetary totals by currency.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_scope": { "type": "object", "properties": { "type": { "type": "string", "enum": ["invoice", "selected_agreements"], "description": "invoice evaluates overall coverage and all retained alerts; selected_agreements evaluates only selected current matches." }, "agreement_ids": { "type": ["array", "null"], "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Null means overall invoice coverage; otherwise only these selected, currently matched agreements." } }, "required": ["type", "agreement_ids"] }, "total_count": { "type": "integer" }, "financially_invalid_count": { "type": "integer" }, "alert_checked_count": { "type": "integer" }, "alert_checkable_count": { "type": "integer" }, "organization_currency": { "type": "object", "properties": { "currency_code": { "type": "string" }, "alert_checked_amount": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Checked amount including VAT in organization currency. Historical invoice-date rates; null if any contributing amount or conversion is unavailable.", "example": "1250.00" }, "alert_checkable_amount": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Eligible amount including VAT in organization currency. Historical invoice-date rates; null if any contributing amount or conversion is unavailable.", "example": "1250.00" }, "incomplete_invoice_count": { "type": "integer", "description": "Eligible invoices missing an amount, currency, or required historical exchange rate/date. Same-currency invoices need no rate or date." } }, "required": [ "currency_code", "alert_checked_amount", "alert_checkable_amount", "incomplete_invoice_count" ] }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "currency_code": { "type": ["string", "null"] }, "invoice_count": { "type": "integer" }, "alert_checked_count": { "type": "integer" }, "alert_checkable_count": { "type": "integer" }, "alert_checked_amount": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "alert_checkable_amount": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "total_amount_excluding_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" }, "total_amount_including_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; retain as decimal text rather than a floating-point number.", "example": "1250.00" } }, "required": [ "currency_code", "invoice_count", "alert_checked_count", "alert_checkable_count", "alert_checked_amount", "alert_checkable_amount", "total_amount_excluding_vat", "total_amount_including_vat" ] } } }, "required": [ "alert_scope", "total_count", "financially_invalid_count", "alert_checked_count", "alert_checkable_count", "organization_currency", "currencies" ] }, "example": { "alert_scope": { "type": "invoice", "agreement_ids": null }, "total_count": 2, "financially_invalid_count": 0, "alert_checked_count": 0, "alert_checkable_count": 2, "organization_currency": { "currency_code": "NOK", "alert_checked_amount": "0", "alert_checkable_amount": "3000.00", "incomplete_invoice_count": 0 }, "currencies": [ { "currency_code": "NOK", "invoice_count": 1, "alert_checked_count": 0, "alert_checkable_count": 1, "alert_checked_amount": "0", "alert_checkable_amount": "125.00", "total_amount_excluding_vat": "100.00", "total_amount_including_vat": "125.00" }, { "currency_code": "EUR", "invoice_count": 1, "alert_checked_count": 0, "alert_checkable_count": 1, "alert_checked_amount": "0", "alert_checkable_amount": "250.00", "total_amount_excluding_vat": "200.00", "total_amount_including_vat": "250.00" } ] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices", "tags": ["Invoices"], "description": "Forward pagination with stable UUID ties and explicit null ordering. Reuse the cursor with the same sort and filters. Use agreement_ids to list invoices currently matched to any selected agreement. Reading matches does not run matching.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true." }, "required": false, "description": "Match the shared teams the authenticated user belongs to in this organization. Teams combine with OR; other filters combine with AND. No memberships or saved rules means no matches. Cannot be combined with team_ids when true.", "name": "mine", "in": "query" }, { "schema": { "type": "string", "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409." }, "required": false, "description": "Shared team IDs (maximum 50; comma-separated in a query string, a JSON array in a command body). Teams combine with OR. Missing, foreign, or personal teams return 404; invalid saved rules return 409.", "name": "team_ids", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match on invoice number or title." }, "required": false, "description": "Case-insensitive substring match on invoice number or title.", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "Match any canonical supplier UUID or literal null for no supplier. Maximum 50 comma-separated values; omit for all suppliers. Empty entries are invalid." }, "required": false, "description": "Match any canonical supplier UUID or literal null for no supplier. Maximum 50 comma-separated values; omit for all suppliers. Empty entries are invalid.", "name": "supplier_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match any canonical recipient UUID or literal null for no recipient. Maximum 50 comma-separated values; omit for all recipients. Empty entries are invalid." }, "required": false, "description": "Match any canonical recipient UUID or literal null for no recipient. Maximum 50 comma-separated values; omit for all recipients. Empty entries are invalid.", "name": "recipient_ids", "in": "query" }, { "schema": { "type": "string", "description": "Match any listed category: invoice, credit_note, self_billed_invoice. Maximum 50 comma-separated values; omit for all categories." }, "required": false, "description": "Match any listed category: invoice, credit_note, self_billed_invoice. Maximum 50 comma-separated values; omit for all categories.", "name": "categories", "in": "query" }, { "schema": { "type": "string", "description": "Match any three-letter currency code (case-insensitive), or literal null for unknown currency. Maximum 50 comma-separated values; omit for all currencies. Example: NOK,EUR,null." }, "required": false, "description": "Match any three-letter currency code (case-insensitive), or literal null for unknown currency. Maximum 50 comma-separated values; omit for all currencies. Example: NOK,EUR,null.", "name": "currency_codes", "in": "query" }, { "schema": { "type": "string", "enum": ["and", "or"], "default": "and", "description": "and requires every supplied column filter; or requires at least one. Both bounds within each date range must match, and that range is one group member. Organization, published/deleted state, search, agreement_ids and mine/team scope are always required outside the group. No column filters means no group restriction." }, "required": false, "description": "and requires every supplied column filter; or requires at least one. Both bounds within each date range must match, and that range is one group member. Organization, published/deleted state, search, agreement_ids and mine/team scope are always required outside the group. No column filters means no group restriction.", "name": "join_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to supplier_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to supplier_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "supplier_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to recipient_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to recipient_ids: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "recipient_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to categories: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to categories: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "category_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to currency_codes: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to currency_codes: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "currency_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to confidence_levels: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to confidence_levels: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "confidence_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to check_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to check_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "check_status_operator", "in": "query" }, { "schema": { "type": "string", "enum": ["is", "is_not"], "default": "is", "description": "Apply to alert_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded." }, "required": false, "description": "Apply to alert_statuses: is matches any selected value; is_not excludes all selected values. Omitted selections add no restriction. is_not requires a selection. For nullable fields, exclusion includes null unless null is explicitly excluded.", "name": "alert_status_operator", "in": "query" }, { "schema": { "type": "string", "description": "Combined alert status, in precedence order: credited (fully financially covered by credit notes), checking (active checks), has_issues (pending or claimed alerts), clean (completed coverage without open alerts), not_checked (all remaining coverage). Uses alert_scope. Comma-separated, maximum 50; omit for all states." }, "required": false, "description": "Combined alert status, in precedence order: credited (fully financially covered by credit notes), checking (active checks), has_issues (pending or claimed alerts), clean (completed coverage without open alerts), not_checked (all remaining coverage). Uses alert_scope. Comma-separated, maximum 50; omit for all states.", "name": "alert_statuses", "in": "query" }, { "schema": { "type": "string", "description": "Original extraction confidence: high, mid, low or unknown. Both successful creating-import stages must retain confidence assessments and stage fingerprints; publication validates their respective cache keys. The lower level wins. Structured/XML creation and unavailable history are unknown. Comma-separated, maximum 50; omit for all levels." }, "required": false, "description": "Original extraction confidence: high, mid, low or unknown. Both successful creating-import stages must retain confidence assessments and stage fingerprints; publication validates their respective cache keys. The lower level wins. Structured/XML creation and unavailable history are unknown. Comma-separated, maximum 50; omit for all levels.", "name": "confidence_levels", "in": "query" }, { "schema": { "type": "string", "description": "Canonical check coverage in alert_scope: not_checkable (credit note or recorded credit-note match), checking (active work), not_checked (no check recorded), completed (all current matches checked), incomplete (missing, failed, cancelled, outdated or unknown coverage). Comma-separated, maximum 50; omit for all states." }, "required": false, "description": "Canonical check coverage in alert_scope: not_checkable (credit note or recorded credit-note match), checking (active work), not_checked (no check recorded), completed (all current matches checked), incomplete (missing, failed, cancelled, outdated or unknown coverage). Comma-separated, maximum 50; omit for all states.", "name": "check_statuses", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires at least one recorded credit-note relationship; false selects zero. For invoice/self_billed_invoice this means linked credit notes; for credit_note this means matched invoices. Includes retained links to soft-deleted counterparts. Does not establish financial resolution. Omit for either." }, "required": false, "description": "true requires at least one recorded credit-note relationship; false selects zero. For invoice/self_billed_invoice this means linked credit notes; for credit_note this means matched invoices. Includes retained links to soft-deleted counterparts. Does not establish financial resolution. Omit for either.", "name": "has_recorded_match", "in": "query" }, { "schema": { "type": "string", "enum": ["invoice", "selected_agreements"], "default": "invoice", "description": "Selected scope requires agreement_ids and evaluates only currently matched selected agreements. Applies to checks, alert counts, filters and metrics." }, "required": false, "description": "Selected scope requires agreement_ids and evaluates only currently matched selected agreements. Applies to checks, alert counts, filters and metrics.", "name": "alert_scope", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Earliest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Earliest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "issued_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Latest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Latest issue date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "issued_through", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Earliest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Earliest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "due_from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Latest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound." }, "required": false, "description": "Latest due date (YYYY-MM-DD), inclusive. Unknown dates do not match this range. Omit for no bound.", "name": "due_through", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Filter by deterministic financial validation, independent of extraction confidence or human approval." }, "required": false, "description": "Filter by deterministic financial validation, independent of extraction confidence or human approval.", "name": "financially_valid", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Filter by explicit human extraction confirmation. Does not change confidence or financial validity." }, "required": false, "description": "Filter by explicit human extraction confirmation. Does not change confidence or financial validity.", "name": "extraction_confirmed", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true selects unconfirmed low/mid extraction confidence, unmatched credit notes, or financially invalid invoices. false selects the exact complement. Always combines with the other selection using AND. Unknown confidence alone does not recommend review." }, "required": false, "description": "true selects unconfirmed low/mid extraction confidence, unmatched credit notes, or financially invalid invoices. false selects the exact complement. Always combines with the other selection using AND. Unknown confidence alone does not recommend review.", "name": "review_recommended", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated agreement IDs (maximum 50). Select invoices matched to any listed agreement in the target organization, regardless of agreement status. Unknown, deleted, or foreign agreements contribute no matches. Combines with other filters using AND; invoices are returned and counted once even if matched to several selected agreements." }, "required": false, "description": "Comma-separated agreement IDs (maximum 50). Select invoices matched to any listed agreement in the target organization, regardless of agreement status. Unknown, deleted, or foreign agreements contribute no matches. Combines with other filters using AND; invoices are returned and counted once even if matched to several selected agreements.", "name": "agreement_ids", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires at least one current organization-owned, nondeleted agreement match; false requires none. Omit for either. Independent of credit-note matching and completed checks." }, "required": false, "description": "true requires at least one current organization-owned, nondeleted agreement match; false requires none. Omit for either. Independent of credit-note matching and completed checks.", "name": "has_agreement_match", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true is equivalent to check_statuses=completed in alert_scope; false includes every other state. Omit for either." }, "required": false, "description": "true is equivalent to check_statuses=completed in alert_scope; false includes every other state. Omit for either.", "name": "alert_checked", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true excludes credit notes and invoices with recorded credit-note matches; false selects those excluded resources. Eligibility is invoice-wide even in selected-agreement scope. Omit for either." }, "required": false, "description": "true excludes credit notes and invoices with recorded credit-note matches; false selects those excluded resources. Eligibility is invoice-wide even in selected-agreement scope. Omit for either.", "name": "alert_checkable", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "true requires retained pending or claimed alerts in alert_scope (including outdated findings); false requires none. No open alerts does not prove completed checks. Omit for either." }, "required": false, "description": "true requires retained pending or claimed alerts in alert_scope (including outdated findings); false requires none. No open alerts does not prove completed checks. Omit for either.", "name": "has_open_alerts", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "default": "false", "description": "false selects active invoices; true selects only soft-deleted invoices." }, "required": false, "description": "false selects active invoices; true selects only soft-deleted invoices.", "name": "deleted", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "created_at", "issued_date", "due_date", "total_amount", "invoice_number", "supplier", "recipient" ], "default": "created_at", "description": "Sort the full selection. supplier/recipient use current canonical names, not snapshots. total_amount uses total_amount_including_vat. Nulls sort last; invoice UUID breaks ties in the same direction. For invoice-date order use issued_date explicitly." }, "required": false, "description": "Sort the full selection. supplier/recipient use current canonical names, not snapshots. total_amount uses total_amount_including_vat. Nulls sort last; invoice UUID breaks ties in the same direction. For invoice-date order use issued_date explicitly.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc", "description": "Ascending or descending primary sort and UUID tie-breaker; nulls always last." }, "required": false, "description": "Ascending or descending primary sort and UUID tie-breaker; nulls always last.", "name": "direction", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of invoice summaries; next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSummary" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "One or more selected teams have invalid saved filter rules. Update the team filters before retrying.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createInvoice", "summary": "Create an invoice from structured data", "tags": ["Invoices"], "description": "Requires financially consistent structured data. An active invoice with the same supplier, recipient, invoice number, issued date, category, currency, and normalized total returns 409 without creating another invoice. Idempotency-Key is optional and protects request retries. Validation failure commits neither the invoice nor its idempotency receipt. Reusing a committed key with different input returns 409. A replay returns the same invoice ID with its current values, including subsequent edits. If that invoice was permanently deleted, replay returns 409; the key remains reserved.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "description": "The complete encoded JSON body, including all line data, must be at most 2 MiB (2,097,152 bytes). Individual field and line-count limits also apply.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "string", "format": "uuid" }, "recipient_id": { "type": "string", "format": "uuid" }, "category": { "type": "string", "enum": ["invoice", "credit_note", "self_billed_invoice"] }, "invoice_number": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "issued_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "due_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "total_amount_including_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "total_amount_excluding_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": null }, "original_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "default": null }, "currency_conversion_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "1" }, "delivery": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "city": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "state": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "postal_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "country_code": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "default": null } }, "additionalProperties": false } }, "default": null, "required": ["address"], "additionalProperties": false }, "credit_note_invoice_reference": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "payment_reference": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "bank_account_number": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "order_references": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 50, "default": [] }, "buyer_reference": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "seller_reference": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "contract_reference": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "project_reference": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "accounting_cost": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "product_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "notes": { "type": ["string", "null"], "maxLength": 2000, "default": null } }, "required": ["line_number", "quantity", "unit_price", "total_excluding_vat"], "additionalProperties": false }, "minItems": 1, "maxItems": 500 } }, "required": [ "supplier_id", "recipient_id", "category", "invoice_number", "issued_date", "currency_code", "total_amount_including_vat", "line_items" ], "additionalProperties": false }, "example": { "supplier_id": "11111111-1111-4111-8111-111111111111", "recipient_id": "22222222-2222-4222-8222-222222222222", "invoice_number": "INV-2026-001", "category": "invoice", "issued_date": "2026-09-07", "currency_code": "NOK", "total_amount_including_vat": "125.00", "total_amount_excluding_vat": "100.00", "line_items": [ { "line_number": 1, "description": "Consulting", "quantity": "1", "unit_price": "100.00", "vat_rate": "0.25", "total_excluding_vat": "100.00" } ] } } } }, "responses": { "200": { "description": "Idempotent replay of an earlier request", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "201": { "description": "Created", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid input or financially inconsistent invoice. Details identify failing fields or checks. The entire write is rolled back; creation failures do not commit an idempotency receipt.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid input or financially inconsistent invoice. Details identify failing fields or checks. The entire write is rolled back; creation failures do not commit an idempotency receipt.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "An active invoice already has the same business identity, or a committed idempotency key has different input or references a permanently deleted resource.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "An active invoice already has the same business identity, or a committed idempotency key has different input or references a permanently deleted resource.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get an invoice", "tags": ["Invoices"], "description": "Returns the published invoice, including soft-deleted invoices. Parties contain invoice snapshots and canonical IDs. Lines and documents are separate paginated collections.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Invoice detail with bounded relationship counts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateInvoice", "summary": "Update an invoice", "tags": ["Invoices"], "description": "Merges changes against the locked current invoice. Financial changes require the complete result to pass validation; failure rolls back the entire edit. Metadata-only edits preserve existing financial errors. Equivalent numeric values are no-ops. Saving does not refresh matching or compliance analysis.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request." }, "required": false, "description": "Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.", "name": "idempotency-key", "in": "header" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "description": "The complete encoded JSON body, including all line data, must be at most 2 MiB (2,097,152 bytes). Individual field and line-count limits also apply.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": ["string", "null"], "format": "uuid" }, "recipient_id": { "type": ["string", "null"], "format": "uuid" }, "category": { "type": "string", "enum": ["invoice", "credit_note", "self_billed_invoice"] }, "invoice_number": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": ["string", "null"], "maxLength": 2000 }, "issued_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "due_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "total_amount_including_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "total_amount_excluding_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "original_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$" }, "currency_conversion_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "delivery": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "city": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "state": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "postal_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "country_code": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "default": null } }, "additionalProperties": false } }, "required": ["address"], "additionalProperties": false }, "credit_note_invoice_reference": { "type": ["string", "null"], "maxLength": 2000 }, "payment_reference": { "type": ["string", "null"], "maxLength": 2000 }, "bank_account_number": { "type": ["string", "null"], "maxLength": 2000 }, "order_references": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 50 }, "buyer_reference": { "type": ["string", "null"], "maxLength": 2000 }, "seller_reference": { "type": ["string", "null"], "maxLength": 2000 }, "contract_reference": { "type": ["string", "null"], "maxLength": 2000 }, "project_reference": { "type": ["string", "null"], "maxLength": 2000 }, "accounting_cost": { "type": ["string", "null"], "maxLength": 2000 }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "product_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "notes": { "type": ["string", "null"], "maxLength": 2000, "default": null } }, "required": ["line_number", "quantity", "unit_price", "total_excluding_vat"], "additionalProperties": false }, "minItems": 1, "maxItems": 500 }, "supplier_snapshot": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 2000 }, "main_name": { "type": ["string", "null"], "maxLength": 2000 }, "department": { "type": ["string", "null"], "maxLength": 2000 }, "organization_number": { "type": ["string", "null"], "maxLength": 2000 }, "email": { "type": ["string", "null"], "maxLength": 2000 }, "website": { "type": ["string", "null"], "maxLength": 2000 }, "address": { "type": ["object", "null"], "properties": { "street": { "type": ["string", "null"], "maxLength": 2000 }, "city": { "type": ["string", "null"], "maxLength": 2000 }, "state": { "type": ["string", "null"], "maxLength": 2000 }, "postal_code": { "type": ["string", "null"], "maxLength": 2000 }, "country_code": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false } }, "additionalProperties": false }, "recipient_snapshot": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 2000 }, "main_name": { "type": ["string", "null"], "maxLength": 2000 }, "department": { "type": ["string", "null"], "maxLength": 2000 }, "organization_number": { "type": ["string", "null"], "maxLength": 2000 }, "email": { "type": ["string", "null"], "maxLength": 2000 }, "website": { "type": ["string", "null"], "maxLength": 2000 }, "address": { "type": ["object", "null"], "properties": { "street": { "type": ["string", "null"], "maxLength": 2000 }, "city": { "type": ["string", "null"], "maxLength": 2000 }, "state": { "type": ["string", "null"], "maxLength": 2000 }, "postal_code": { "type": ["string", "null"], "maxLength": 2000 }, "country_code": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false } }, "additionalProperties": false }, "payment_override": { "type": ["object", "null"], "properties": { "outstanding_amount": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["outstanding_amount"], "additionalProperties": false }, "extraction_confirmed": { "type": "boolean" }, "line_item_changes": { "type": "object", "properties": { "create": { "type": "array", "items": { "type": "object", "properties": { "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "product_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "notes": { "type": ["string", "null"], "maxLength": 2000, "default": null } }, "required": [ "line_number", "quantity", "unit_price", "total_excluding_vat" ], "additionalProperties": false }, "maxItems": 500, "default": [] }, "update": { "type": "array", "items": { "type": "object", "properties": { "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000 }, "product_code": { "type": ["string", "null"], "maxLength": 2000 }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000 }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "notes": { "type": ["string", "null"], "maxLength": 2000 }, "id": { "type": "string", "format": "uuid" } }, "required": ["id"], "additionalProperties": false }, "maxItems": 500, "default": [] }, "remove": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 500, "default": [] } }, "additionalProperties": false }, "matched_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 } }, "additionalProperties": false }, "example": { "title": "September consulting" } } } }, "responses": { "200": { "description": "Invoice after the atomic update, or unchanged invoice for a no-op.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid input or financially inconsistent invoice. Details identify failing fields or checks. The entire edit is rolled back.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid input or financially inconsistent invoice. Details identify failing fields or checks. The entire edit is rolled back.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The resulting business identity matches another active invoice, or a credit note linked to a claim cannot be changed to another category.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "The resulting business identity matches another active invoice, or a credit note linked to a claim cannot be changed to another category.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteInvoice", "summary": "Soft-delete an invoice", "tags": ["Invoices"], "description": "Repeatable: deleting an already deleted invoice succeeds. Source documents and prior analysis remain available.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Invoice with deleted_at set.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Claim evidence or concurrent relationship changes prevent deletion.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Claim evidence or concurrent relationship changes prevent deletion.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/restore": { "post": { "operationId": "restoreInvoice", "summary": "Restore an invoice", "tags": ["Invoices"], "description": "Repeatable: restoring an active invoice succeeds. Returns 409 if another active invoice has claimed the same business identity; the invoice remains deleted.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Invoice with deleted_at cleared.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Another active invoice has the same business identity.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Another active invoice has the same business identity.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/line-items": { "get": { "operationId": "listInvoiceLineItems", "summary": "List invoice line items", "tags": ["Invoices"], "description": "Returns stored line IDs, original financial values, and deterministic line-level financial errors.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of invoice lines; next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createInvoiceLineItem", "summary": "Add one invoice line", "tags": ["Invoices"], "description": "Uses the complete-invoice correction planner. The line number must be unused and the complete invoice must remain financially valid. Use invoice PATCH to add a line and correct headers atomically. The response is the invoice; read the line collection for the assigned ID.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "product_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "notes": { "type": ["string", "null"], "maxLength": 2000, "default": null } }, "required": ["line_number", "quantity", "unit_price", "total_excluding_vat"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Invoice after the addition.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid correction or category selection, including an invalid financial result.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid correction or category selection, including an invalid financial result.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Invoice, relationship, or claim conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Invoice, relationship, or claim conflict.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/documents": { "get": { "operationId": "listInvoiceDocuments", "summary": "List invoice documents", "tags": ["Invoices"], "description": "Returns authorized source Documents and their primary/attachment roles and positions.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of document relationships; next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDocument" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "attachInvoiceDocument", "summary": "Attach a Document to an invoice", "tags": ["Invoices"], "description": "Attaches an uploaded organization-owned Document as non-primary. Each attachment must be 100 bytes to 25 MiB; there is no attachment-count or combined-size cap. Replays return the current relationship, including a subsequently selected primary role. Published invoices, including soft-deleted invoices, can be edited. Does not extract or check the invoice.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid" } }, "required": ["document_id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Current invoice Document relationship.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDocument" } } } }, "201": { "description": "Current invoice Document relationship.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDocument" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The relationship conflicts with existing evidence, or the uploaded bytes are missing or changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "The relationship conflicts with existing evidence, or the uploaded bytes are missing or changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/documents/{document_id}/set-primary": { "post": { "operationId": "setInvoicePrimaryDocument", "summary": "Select the primary invoice Document", "tags": ["Invoices"], "description": "Atomically promotes an attached Document and demotes the previous primary. Positions and original import sources remain unchanged. Selecting the existing primary is a no-op.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "document_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current invoice Document relationship.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDocument" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The relationship conflicts with existing evidence, or the uploaded bytes are missing or changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "The relationship conflicts with existing evidence, or the uploaded bytes are missing or changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/documents/{document_id}": { "delete": { "operationId": "unlinkInvoiceDocument", "summary": "Unlink an invoice Document", "tags": ["Invoices"], "description": "Removes only the relationship; retains the Document, bytes, import history and prior findings. Requires another Document to be explicitly promoted before unlinking the primary. Unreleased claim membership blocks removal, including cancelled claims. An already-absent relationship returns 204 after invoice and Document authorization.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "document_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Relationship absent." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "The relationship conflicts with existing evidence, or the uploaded bytes are missing or changed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict_source_unavailable" }, "example": { "error": { "code": "conflict", "message": "The relationship conflicts with existing evidence, or the uploaded bytes are missing or changed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/preview-category-change": { "post": { "operationId": "previewInvoiceCategoryChange", "summary": "Preview category and pending corrections", "tags": ["Invoices"], "description": "Performs no writes. Includes complete financial diagnostics, party resolution, affected matches and claim conflicts. Exact-reference candidates are bounded at 100 and never selected automatically. PATCH reloads and validates current state.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": ["string", "null"], "format": "uuid" }, "recipient_id": { "type": ["string", "null"], "format": "uuid" }, "category": { "type": "string", "enum": ["invoice", "credit_note", "self_billed_invoice"] }, "invoice_number": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": ["string", "null"], "maxLength": 2000 }, "issued_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "due_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "total_amount_including_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "total_amount_excluding_vat": { "type": ["string", "null"], "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "original_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$" }, "currency_conversion_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "delivery": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "city": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "state": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "postal_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "country_code": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "default": null } }, "additionalProperties": false } }, "required": ["address"], "additionalProperties": false }, "credit_note_invoice_reference": { "type": ["string", "null"], "maxLength": 2000 }, "payment_reference": { "type": ["string", "null"], "maxLength": 2000 }, "bank_account_number": { "type": ["string", "null"], "maxLength": 2000 }, "order_references": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 50 }, "buyer_reference": { "type": ["string", "null"], "maxLength": 2000 }, "seller_reference": { "type": ["string", "null"], "maxLength": 2000 }, "contract_reference": { "type": ["string", "null"], "maxLength": 2000 }, "project_reference": { "type": ["string", "null"], "maxLength": 2000 }, "accounting_cost": { "type": ["string", "null"], "maxLength": 2000 }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "product_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "notes": { "type": ["string", "null"], "maxLength": 2000, "default": null } }, "required": ["line_number", "quantity", "unit_price", "total_excluding_vat"], "additionalProperties": false }, "minItems": 1, "maxItems": 500 }, "supplier_snapshot": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 2000 }, "main_name": { "type": ["string", "null"], "maxLength": 2000 }, "department": { "type": ["string", "null"], "maxLength": 2000 }, "organization_number": { "type": ["string", "null"], "maxLength": 2000 }, "email": { "type": ["string", "null"], "maxLength": 2000 }, "website": { "type": ["string", "null"], "maxLength": 2000 }, "address": { "type": ["object", "null"], "properties": { "street": { "type": ["string", "null"], "maxLength": 2000 }, "city": { "type": ["string", "null"], "maxLength": 2000 }, "state": { "type": ["string", "null"], "maxLength": 2000 }, "postal_code": { "type": ["string", "null"], "maxLength": 2000 }, "country_code": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false } }, "additionalProperties": false }, "recipient_snapshot": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 2000 }, "main_name": { "type": ["string", "null"], "maxLength": 2000 }, "department": { "type": ["string", "null"], "maxLength": 2000 }, "organization_number": { "type": ["string", "null"], "maxLength": 2000 }, "email": { "type": ["string", "null"], "maxLength": 2000 }, "website": { "type": ["string", "null"], "maxLength": 2000 }, "address": { "type": ["object", "null"], "properties": { "street": { "type": ["string", "null"], "maxLength": 2000 }, "city": { "type": ["string", "null"], "maxLength": 2000 }, "state": { "type": ["string", "null"], "maxLength": 2000 }, "postal_code": { "type": ["string", "null"], "maxLength": 2000 }, "country_code": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false } }, "additionalProperties": false }, "payment_override": { "type": ["object", "null"], "properties": { "outstanding_amount": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" } }, "required": ["outstanding_amount"], "additionalProperties": false }, "extraction_confirmed": { "type": "boolean" }, "line_item_changes": { "type": "object", "properties": { "create": { "type": "array", "items": { "type": "object", "properties": { "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "product_code": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000, "default": null }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$", "default": "0" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "notes": { "type": ["string", "null"], "maxLength": 2000, "default": null } }, "required": [ "line_number", "quantity", "unit_price", "total_excluding_vat" ], "additionalProperties": false }, "maxItems": 500, "default": [] }, "update": { "type": "array", "items": { "type": "object", "properties": { "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000 }, "product_code": { "type": ["string", "null"], "maxLength": 2000 }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000 }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "notes": { "type": ["string", "null"], "maxLength": 2000 }, "id": { "type": "string", "format": "uuid" } }, "required": ["id"], "additionalProperties": false }, "maxItems": 500, "default": [] }, "remove": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 500, "default": [] } }, "additionalProperties": false }, "matched_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 } }, "required": ["category"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Advisory category plan.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "enum": ["invoice", "credit_note", "self_billed_invoice"] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "from": { "$ref": "#/components/schemas/InvoiceCorrectionValue" }, "to": { "$ref": "#/components/schemas/InvoiceCorrectionValue" } }, "required": ["field", "from", "to"] } }, "line_changes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": ["string", "null"], "format": "uuid" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "from": { "$ref": "#/components/schemas/InvoiceCorrectionValue" }, "to": { "$ref": "#/components/schemas/InvoiceCorrectionValue" } }, "required": ["field", "from", "to"] } } }, "required": ["id", "changes"] } }, "removed_line_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "parties": { "type": "object", "properties": { "supplier": { "type": "object", "properties": { "id": { "type": ["string", "null"], "format": "uuid" }, "snapshot": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "organization_number": { "type": ["string", "null"] }, "main_name": { "type": ["string", "null"] }, "department": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] }, "website": { "type": ["string", "null"] }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] }, "state": { "type": ["string", "null"] }, "postal_code": { "type": ["string", "null"] }, "country_code": { "type": ["string", "null"] } }, "required": [ "street", "city", "state", "postal_code", "country_code" ] } }, "required": [ "name", "organization_number", "main_name", "department", "email", "website", "address" ] } }, "required": ["id", "snapshot"] }, "recipient": { "type": "object", "properties": { "id": { "type": ["string", "null"], "format": "uuid" }, "snapshot": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "organization_number": { "type": ["string", "null"] }, "main_name": { "type": ["string", "null"] }, "department": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] }, "website": { "type": ["string", "null"] }, "address": { "type": "object", "properties": { "street": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] }, "state": { "type": ["string", "null"] }, "postal_code": { "type": ["string", "null"] }, "country_code": { "type": ["string", "null"] } }, "required": [ "street", "city", "state", "postal_code", "country_code" ] } }, "required": [ "name", "organization_number", "main_name", "department", "email", "website", "address" ] } }, "required": ["id", "snapshot"] } }, "required": ["supplier", "recipient"] }, "financially_valid": { "type": "boolean" }, "financial_errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_financial_inputs", "line_calculation_mismatch", "invoice_total_mismatch", "invoice_subtotal_mismatch", "category_amount_mismatch" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "field", "message"] } }, "affected_matches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": ["retain", "remove"] } }, "required": ["id", "invoice_id", "action"] } }, "selected_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "retained_finding_count": { "type": "integer" }, "claim_conflicts": { "type": "array", "items": { "type": "object", "properties": { "claim_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string" } }, "required": ["claim_id", "reason"] } }, "exact_reference_candidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": ["string", "null"] }, "category": { "type": "string", "enum": ["invoice", "credit_note", "self_billed_invoice"] }, "supplier_id": { "type": ["string", "null"], "format": "uuid" }, "currency_code": { "type": ["string", "null"] }, "total_amount_including_vat": { "type": ["string", "null"] } }, "required": [ "id", "invoice_number", "category", "supplier_id", "currency_code", "total_amount_including_vat" ] } }, "candidates_truncated": { "type": "boolean" }, "requires_matched_invoice_ids": { "type": "boolean" } }, "required": [ "category", "changes", "line_changes", "removed_line_ids", "parties", "financially_valid", "financial_errors", "affected_matches", "selected_invoice_ids", "retained_finding_count", "claim_conflicts", "exact_reference_candidates", "candidates_truncated", "requires_matched_invoice_ids" ] } } } }, "400": { "description": "Invalid correction or category selection, including an invalid financial result.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid correction or category selection, including an invalid financial result.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Invoice, relationship, or claim conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Invoice, relationship, or claim conflict.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/line-items/{line_item_id}": { "patch": { "operationId": "updateInvoiceLineItem", "summary": "Correct one invoice line", "tags": ["Invoices"], "description": "Uses the complete-invoice correction planner. Financial corrections must leave the complete invoice valid. Use invoice PATCH to repair headers and lines atomically.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "line_item_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "line_number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "description": { "type": ["string", "null"], "maxLength": 2000 }, "product_code": { "type": ["string", "null"], "maxLength": 2000 }, "quantity": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "unit": { "type": ["string", "null"], "maxLength": 2000 }, "unit_price": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "discount_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "surcharge_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "vat_rate": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "total_excluding_vat": { "type": "string", "maxLength": 100, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "period_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "period_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "notes": { "type": ["string", "null"], "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Invoice after correction.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid correction or category selection, including an invalid financial result.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid correction or category selection, including an invalid financial result.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Invoice, relationship, or claim conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Invoice, relationship, or claim conflict.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteInvoiceLineItem", "summary": "Remove one invoice line", "tags": ["Invoices"], "description": "Retains findings by detaching their line reference. The complete result must be financially valid. Use invoice PATCH when totals also need correction. An absent line is a no-op.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "line_item_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Line absent." }, "400": { "description": "Invalid correction or category selection, including an invalid financial result.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid correction or category selection, including an invalid financial result.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Invoice, relationship, or claim conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Invoice, relationship, or claim conflict.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/matched-invoices": { "get": { "operationId": "listMatchedInvoices", "summary": "List linked invoices of every category", "tags": ["Invoices"], "description": "Reads both directions, including retained inactive relationships. Follow next_cursor for all matches. Only active relationships provide credit coverage.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of matches and counterpart invoices.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MatchedInvoice" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid match request, including linking an invoice to itself.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid match request, including linking an invoice to itself.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Invalid pair, inactive invoice, or a concurrent scope change. Retry scope conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Invalid pair, inactive invoice, or a concurrent scope change. Retry scope conflicts.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/match-invoice": { "post": { "operationId": "matchInvoice", "summary": "Manually match another invoice", "tags": ["Invoices"], "description": "Accepts either side of a credit-note and invoice/self-billed pair. Both invoices must be active and published. Supplier and currency differences are allowed. Repeats are no-ops; an automatic match is promoted while preserving its ID.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string", "format": "uuid" } }, "required": ["invoice_id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Current manual match.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchedInvoice" } } } }, "400": { "description": "Invalid match request, including linking an invoice to itself.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid match request, including linking an invoice to itself.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Invalid pair, inactive invoice, or a concurrent scope change. Retry scope conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Invalid pair, inactive invoice, or a concurrent scope change. Retry scope conflicts.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/invoices/{id}/matches/{match_id}": { "delete": { "operationId": "deleteInvoiceMatch", "summary": "Delete a specific invoice match", "tags": ["Invoices"], "description": "Either participating invoice may be the parent. Missing matches return 204; an old match ID cannot remove a recreated relationship.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "match_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Match absent." }, "400": { "description": "Invalid match request, including linking an invoice to itself.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid match request, including linking an invoice to itself.", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Invalid pair, inactive invoice, or a concurrent scope change. Retry scope conflicts.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Invalid pair, inactive invoice, or a concurrent scope change. Retry scope conflicts.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/suppliers": { "get": { "operationId": "listSuppliers", "summary": "List suppliers", "tags": ["Parties"], "description": "List suppliers in the active organization, ordered by name and UUID. Requires Read access. Search filters names case-insensitively. Returns compact records with id, name, and organization_number. Retrieve a record by ID for its full details. Pass next_cursor as cursor with the same search to retrieve the next page.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match on name. Omit to list all records." }, "required": false, "description": "Case-insensitive substring match on name. Omit to list all records.", "name": "search", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of suppliers; next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_number": { "type": ["string", "null"] } }, "required": ["id", "name", "organization_number"] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createSupplier", "summary": "Create a supplier", "tags": ["Parties"], "description": "Create a canonical party. Only name is required. Omitted contact fields are stored as null; a missing registration country may be inferred as described below. Websites must be absolute HTTP(S) URLs. Organization numbers use the shared country-specific format and checksum rules described on organization_number. Recognized valid wrappers are accepted and checksum-verified identifiers are stored canonically. A supplied registration country is authoritative; otherwise a recognized prefix is checked before the address country. Countries are inferred only after checksum success, and a failed recognized prefix never falls back to the address. Unsupported and format-only identifiers receive basic input validation without country inference. No idempotency key is required; repeating a create returns a duplicate conflict.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateParty" } } } }, "responses": { "201": { "description": "Current canonical party master record. Invoice party fields remain captured invoice snapshots.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "An existing party has the same normalized organization number and issuing country (missing countries share one group), or both parties lack a number and have the same normalized name. No records are merged. existing_party identifies an authorized conflicting record when available. The entire write is rolled back.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "An existing party has the same normalized organization number and issuing country (missing countries share one group), or both parties lack a number and have the same normalized name. No records are merged. existing_party identifies an authorized conflicting record when available. The entire write is rolled back.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/recipients": { "get": { "operationId": "listRecipients", "summary": "List recipients", "tags": ["Parties"], "description": "List recipients in the active organization, ordered by name and UUID. Requires Read access. Search filters names case-insensitively. Returns compact records with id, name, and organization_number. Retrieve a record by ID for its full details. Pass next_cursor as cursor with the same search to retrieve the next page.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match on name. Omit to list all records." }, "required": false, "description": "Case-insensitive substring match on name. Omit to list all records.", "name": "search", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of recipients; next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_number": { "type": ["string", "null"] } }, "required": ["id", "name", "organization_number"] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createRecipient", "summary": "Create a recipient", "tags": ["Parties"], "description": "Create a canonical party. Only name is required. Omitted contact fields are stored as null; a missing registration country may be inferred as described below. Websites must be absolute HTTP(S) URLs. Organization numbers use the shared country-specific format and checksum rules described on organization_number. Recognized valid wrappers are accepted and checksum-verified identifiers are stored canonically. A supplied registration country is authoritative; otherwise a recognized prefix is checked before the address country. Countries are inferred only after checksum success, and a failed recognized prefix never falls back to the address. Unsupported and format-only identifiers receive basic input validation without country inference. No idempotency key is required; repeating a create returns a duplicate conflict.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateParty" } } } }, "responses": { "201": { "description": "Current canonical party master record. Invoice party fields remain captured invoice snapshots.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "409": { "description": "An existing party has the same normalized organization number and issuing country (missing countries share one group), or both parties lack a number and have the same normalized name. No records are merged. existing_party identifies an authorized conflicting record when available. The entire write is rolled back.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "An existing party has the same normalized organization number and issuing country (missing countries share one group), or both parties lack a number and have the same normalized name. No records are merged. existing_party identifies an authorized conflicting record when available. The entire write is rolled back.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/teams": { "get": { "operationId": "listTeams", "summary": "List teams", "tags": ["Teams"], "description": "List shared teams in the active organization, ordered by name and UUID. Requires Read access. Search filters names case-insensitively. Personal subscriptions are excluded. Returns id and name, with organization_number always null. Retrieve /v1/teams/{id} for the saved filter and /v1/teams/{id}/members for membership. Pass next_cursor as cursor with the same search to retrieve the next page.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match on name. Omit to list all records." }, "required": false, "description": "Case-insensitive substring match on name. Omit to list all records.", "name": "search", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of teams; next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_number": { "type": ["string", "null"] } }, "required": ["id", "name", "organization_number"] }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] }, "example": { "data": [ { "id": "b2e8ad3a-12f4-4c4b-aadc-5750552b7738", "name": "Engineering", "organization_number": null } ], "next_cursor": null } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "createTeam", "summary": "Create a shared team", "tags": ["Teams"], "description": "Create a shared team with a trimmed name of 1–100 characters and an optional saved filter. Names are unique case-sensitively within the organization. Optional initial user_ids are validated and added atomically; an empty team remains valid. An omitted or null filter contributes no matches. Both ordinary organization members and admins can manage teams with Write access. Repeating creation returns a name conflict; no idempotency key is required. Team filters and membership never grant resource access.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeam" } } } }, "responses": { "201": { "description": "Created shared team.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "A shared team with this exact case-sensitive name already exists in the organization. The entire write is rolled back.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "A shared team with this exact case-sensitive name already exists in the organization. The entire write is rolled back.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/teams/{id}": { "get": { "operationId": "getTeam", "summary": "Get a shared team", "tags": ["Teams"], "description": "Read a shared team and its saved filter verbatim, even if the stored definition is malformed or unsupported. List members separately. Personal subscriptions and foreign teams return 404. Use PATCH to replace or clear invalid filters before retrying filtered resource requests.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Shared team with its saved filter, including invalid legacy JSON.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateTeam", "summary": "Update a shared team", "tags": ["Teams"], "description": "Update name and/or filter atomically. Omitted fields stay unchanged, including invalid legacy filters. A filter object replaces the complete definition; null clears it and contributes no matches. Filter authoring validates fields, operators, values, depth, condition count, and organization-owned references. Empty PATCH returns the current team. No ETag is required. Changes affect subsequent mine/team_ids requests under live pagination; existing cursors do not freeze rules or memberships.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeam" } } } }, "responses": { "200": { "description": "Shared team with its saved filter, including invalid legacy JSON.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "A shared team with this exact case-sensitive name already exists in the organization. The entire write is rolled back.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "A shared team with this exact case-sensitive name already exists in the organization. The entire write is rolled back.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "delete": { "operationId": "deleteTeam", "summary": "Delete a shared team", "tags": ["Teams"], "description": "Permanently delete the shared team, its saved rules, and all membership links. Organization members, business records, and personal subscriptions are unchanged. There is no restore. Missing, already deleted, foreign, and personal-subscription IDs return 404. The team stops contributing to mine; explicit team_ids containing it return 404 on subsequent requests, including later pages.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Team and memberships deleted." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/teams/{id}/members": { "get": { "operationId": "listTeamMembers", "summary": "List shared team members", "tags": ["Teams"], "description": "List team members who currently belong to the selected organization, ordered by opaque user ID. Empty teams return an empty page. Membership is synchronized through the existing organization membership lifecycle.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current shared team members.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "post": { "operationId": "addTeamMember", "summary": "Add a shared team member", "tags": ["Teams"], "description": "Add a current organization member to the shared team. Obtain user_id from GET /v1/members or the principal.user_id in GET /v1/me. Adding an existing member is a successful no-op. Foreign or missing users/teams and personal subscriptions return 404. Membership affects subsequent mine requests by that user; it grants no additional resource access.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTeamMember" } } } }, "responses": { "200": { "description": "Already a team member.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "201": { "description": "Member added to the team.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Location": { "schema": { "type": "string" }, "required": false, "description": "Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/teams/{id}/members/{user_id}": { "delete": { "operationId": "removeTeamMember", "summary": "Remove a shared team member", "tags": ["Teams"], "description": "Remove a current organization member from this shared team. Returns 204 if the user is already absent. Removing the last member is allowed and does not delete the team or its filter; explicit team_ids can still select it. Foreign or missing users/teams and personal subscriptions return 404.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "user_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "204": { "description": "Membership removed from the team." }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/suppliers/{id}/merge": { "post": { "operationId": "mergeSuppliers", "summary": "Merge suppliers", "tags": ["Parties"], "description": "Atomically merge source parties into the retained party. Preserves retained contact details and invoice snapshots, moves canonical invoice references and agreement links, and removes source parties. Supplier alerts and recipient subscription filters are transferred. Returns all affected non-deleted agreements, including previous invoice matches requiring cleanup. Matching runs for affected agreements are admitted in the merge transaction and dispatched after commit. The response includes their workflow_run_ids. Merge requests are not replayable; refresh affected records after an uncertain response.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } }, "required": ["source_ids"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Committed merge and affected agreements.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyMergeResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Concurrent relationship changes. No partial merge is committed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Concurrent relationship changes. No partial merge is committed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/suppliers/delete": { "post": { "operationId": "deleteSuppliers", "summary": "Delete unused suppliers", "tags": ["Parties"], "description": "Delete an organization-owned selection atomically. Any invoice reference, including incomplete or deleted invoices, or any agreement link blocks the entire selection. The response identifies blockers. Missing or foreign IDs return 404 without deleting anything.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } }, "required": ["ids"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Deleted supplier IDs.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": ["deleted_ids"] } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Selection is in use or concurrently changed; no suppliers deleted.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["suppliers_in_use", "conflict"] }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": ["code", "message", "request_id"] }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_count": { "type": "integer" }, "agreement_count": { "type": "integer" } }, "required": ["id", "invoice_count", "agreement_count"] } } }, "required": ["error"] } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/suppliers/directory": { "get": { "operationId": "listSupplierDirectory", "summary": "List supplier directory", "tags": ["Parties"], "description": "Full party records with visible relationship counts and deletion blockers. Cursor pagination is bound to the organization, filters and sort. Name, organization number and email sorting use UUID as the tie-breaker. Counts and filters share visibility rules: completed non-deleted invoices, non-archived agreements, and pending supplier alerts. Compact selectors remain available at the collection root.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": ["name", "organization_number", "email"], "default": "name" }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "required": false, "name": "direction", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "has_invoices", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "has_agreements", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "has_alerts", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Filtered directory page and total.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyDirectoryPage" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/suppliers/{id}": { "get": { "operationId": "getSupplier", "summary": "Get a supplier", "tags": ["Parties"], "description": "Current canonical party master record. Invoice party fields remain captured invoice snapshots.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current canonical party master record. Invoice party fields remain captured invoice snapshots.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateSupplier", "summary": "Update a supplier", "tags": ["Parties"], "description": "Merge supplied fields into the locked current record. Omitted fields and omitted address members stay unchanged; null clears optional values and address:null clears all address fields. Organization-number submissions and country changes validate the resulting pair against the locked record; unrelated edits preserve legacy numbers. Empty and equivalent normalized updates preserve timestamps. Canonical edits preserve invoice snapshots and assessment freshness and do not launch matching or compliance.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateParty" } } } }, "responses": { "200": { "description": "Current canonical party master record. Invoice party fields remain captured invoice snapshots.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "An existing party has the same normalized organization number and issuing country (missing countries share one group), or both parties lack a number and have the same normalized name. No records are merged. existing_party identifies an authorized conflicting record when available. The entire write is rolled back.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "An existing party has the same normalized organization number and issuing country (missing countries share one group), or both parties lack a number and have the same normalized name. No records are merged. existing_party identifies an authorized conflicting record when available. The entire write is rolled back.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/recipients/{id}/merge": { "post": { "operationId": "mergeRecipients", "summary": "Merge recipients", "tags": ["Parties"], "description": "Atomically merge source parties into the retained party. Preserves retained contact details and invoice snapshots, moves canonical invoice references and agreement links, and removes source parties. Supplier alerts and recipient subscription filters are transferred. Returns all affected non-deleted agreements, including previous invoice matches requiring cleanup. Matching runs for affected agreements are admitted in the merge transaction and dispatched after commit. The response includes their workflow_run_ids. Merge requests are not replayable; refresh affected records after an uncertain response.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } }, "required": ["source_ids"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Committed merge and affected agreements.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyMergeResult" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "Concurrent relationship changes. No partial merge is committed.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "Concurrent relationship changes. No partial merge is committed.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/recipients/directory": { "get": { "operationId": "listRecipientDirectory", "summary": "List recipient directory", "tags": ["Parties"], "description": "Full party records with visible relationship counts and deletion blockers. Cursor pagination is bound to the organization, filters and sort. Name, organization number and email sorting use UUID as the tie-breaker. Counts and filters share visibility rules: completed non-deleted invoices, non-archived agreements, and pending supplier alerts. Compact selectors remain available at the collection root.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": ["name", "organization_number", "email"], "default": "name" }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "required": false, "name": "direction", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "has_invoices", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "has_agreements", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Filtered directory page and total.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyDirectoryPage" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/recipients/{id}": { "get": { "operationId": "getRecipient", "summary": "Get a recipient", "tags": ["Parties"], "description": "Current canonical party master record. Invoice party fields remain captured invoice snapshots.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Current canonical party master record. Invoice party fields remain captured invoice snapshots.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } }, "patch": { "operationId": "updateRecipient", "summary": "Update a recipient", "tags": ["Parties"], "description": "Merge supplied fields into the locked current record. Omitted fields and omitted address members stay unchanged; null clears optional values and address:null clears all address fields. Organization-number submissions and country changes validate the resulting pair against the locked record; unrelated edits preserve legacy numbers. Empty and equivalent normalized updates preserve timestamps. Canonical edits preserve invoice snapshots and assessment freshness and do not launch matching or compliance.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateParty" } } } }, "responses": { "200": { "description": "Current canonical party master record. Invoice party fields remain captured invoice snapshots.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "An existing party has the same normalized organization number and issuing country (missing countries share one group), or both parties lack a number and have the same normalized name. No records are merged. existing_party identifies an authorized conflicting record when available. The entire write is rolled back.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "An existing party has the same normalized organization number and issuing country (missing countries share one group), or both parties lack a number and have the same normalized name. No records are merged. existing_party identifies an authorized conflicting record when available. The entire write is rolled back.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/workflow-runs": { "get": { "operationId": "listWorkflowRuns", "summary": "List workflow runs", "tags": ["Workflow runs"], "description": "Lists visible product executions, newest first (created_at, then UUID). Filters are combined with AND; comma-separated values within a filter use OR. Reads include only the shipped public workflow inventory within the requested organization. Follow next_cursor until null. Use status=queued,running to discover active work; poll known ids without a status filter to observe completion. Explicit retries appear as separate runs. Reads do not contact the execution provider.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "maxLength": 4000, "description": "Comma-separated statuses. Omit to include all statuses, including terminal runs." }, "required": false, "description": "Comma-separated statuses. Omit to include all statuses, including terminal runs.", "name": "status", "in": "query" }, { "schema": { "type": "string", "maxLength": 4000, "description": "Comma-separated public workflow types." }, "required": false, "description": "Comma-separated public workflow types.", "name": "type", "in": "query" }, { "schema": { "type": "string", "maxLength": 27, "format": "date-time", "description": "Inclusive creation time, as a UTC timestamp with at most six fractional digits." }, "required": false, "description": "Inclusive creation time, as a UTC timestamp with at most six fractional digits.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "maxLength": 27, "format": "date-time", "description": "Exclusive creation time, as a UTC timestamp with at most six fractional digits." }, "required": false, "description": "Exclusive creation time, as a UTC timestamp with at most six fractional digits.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "invoice_import", "workflow_run", "invoice", "agreement", "document", "integration", "agreement_price_import" ] }, "required": false, "name": "resource_type", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Owner ID; requires resource_type." }, "required": false, "description": "Owner ID; requires resource_type.", "name": "resource_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 4000, "description": "Optional comma-separated run IDs, at most 100. Unknown or inaccessible IDs are omitted." }, "required": false, "description": "Optional comma-separated run IDs, at most 100. Unknown or inaccessible IDs are omitted.", "name": "ids", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of visible runs. next_cursor is null at the end.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRun" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] }, "example": { "data": [ { "id": "44444444-4444-4444-8444-444444444444", "retry_of_run_id": null, "type": "invoice_import", "resource": { "type": "invoice_import", "id": "33333333-3333-4333-8333-333333333333" }, "status": "completed", "progress": { "total": 1, "queued": 0, "running": 0, "completed": 1, "skipped": 0, "failed": 0, "cancelled": 0 }, "created_at": "2026-09-08T12:00:00.000Z", "updated_at": "2026-09-08T12:00:30.000Z", "started_at": "2026-09-08T12:00:02.000Z", "finished_at": "2026-09-08T12:00:30.000Z", "failure": null } ], "next_cursor": null } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/workflow-runs/summary": { "get": { "operationId": "getWorkflowRunSummary", "summary": "Summarize workflow progress", "tags": ["Workflow runs"], "description": "One entry per public workflow type, including idle types. Run counts include retained terminal runs; item progress covers currently active work only. The snapshot token changes with counts, including completions between polls. Poll this bounded summary for background progress; load run lists and results on demand. Reads never contact execution providers.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "Organization-scoped workflow summary.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunSummary" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/workflow-runs/{id}": { "get": { "operationId": "getWorkflowRun", "summary": "Get a workflow run", "tags": ["Workflow runs"], "description": "Returns exactly one product execution using the same representation as the list. Older runs remain addressable after an explicit retry. queued/running are active; completed/completed_with_errors/failed/cancelled are terminal. Progress counts admitted items; total is null while discovery is open. completed_with_errors means settled items include both successes and failures/cancellations. A failed execution is a successful HTTP read (200), with failure details. Provider IDs, attempts, payloads, and extraction evidence are not included.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "One operation, its owning resource, progress, status, timestamps, and failure.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRun" }, "example": { "id": "44444444-4444-4444-8444-444444444444", "retry_of_run_id": null, "type": "invoice_import", "resource": { "type": "invoice_import", "id": "33333333-3333-4333-8333-333333333333" }, "status": "completed", "progress": { "total": 1, "queued": 0, "running": 0, "completed": 1, "skipped": 0, "failed": 0, "cancelled": 0 }, "created_at": "2026-09-08T12:00:00.000Z", "updated_at": "2026-09-08T12:00:30.000Z", "started_at": "2026-09-08T12:00:02.000Z", "finished_at": "2026-09-08T12:00:30.000Z", "failure": null } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/workflow-runs/{id}/cancel": { "post": { "operationId": "cancelWorkflowRun", "summary": "Cancel a workflow run", "tags": ["Workflow runs"], "description": "Cancels this exact execution through the owning domain. Product cancellation stops discovery, cancels pending items, and fences late publication before provider cancellation is requested. Results from already completed items are retained. Repeated cancellation succeeds, including after a new retry; an old run URL never cancels the newer run. Completed, completed_with_errors and failed runs return 409 and retain their result/failure. No request body or Idempotency-Key is needed.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "write", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "The cancelled operation, with already completed item results retained.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRun" }, "example": { "id": "44444444-4444-4444-8444-444444444444", "retry_of_run_id": null, "type": "invoice_import", "resource": { "type": "invoice_import", "id": "33333333-3333-4333-8333-333333333333" }, "status": "cancelled", "progress": { "total": 1, "queued": 0, "running": 0, "completed": 0, "skipped": 0, "failed": 0, "cancelled": 1 }, "created_at": "2026-09-08T12:00:00.000Z", "updated_at": "2026-09-08T12:00:30.000Z", "started_at": "2026-09-08T12:00:02.000Z", "finished_at": "2026-09-08T12:00:30.000Z", "failure": null } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "409": { "description": "This run completed, failed, or was superseded and cannot be cancelled.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_conflict" }, "example": { "error": { "code": "conflict", "message": "This run completed, failed, or was superseded and cannot be cancelled.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/workflow-runs/{id}/items": { "get": { "operationId": "listWorkflowRunItems", "summary": "List workflow run items", "tags": ["Workflow runs"], "description": "Lists admitted work items ordered by created_at, then UUID, ascending. Filter status with comma-separated values. Results are available as each item finishes, even if siblings remain active or the parent fails or is cancelled. Follow next_cursor with unchanged filters. A null cursor means the current page is exhausted, not that discovery or processing has finished; poll the parent for completion and restart item listing when refreshing changed statuses. Reads never contact the execution provider.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results per page." }, "required": false, "description": "Maximum number of results per page.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 4096, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page." }, "required": false, "description": "Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "maxLength": 4000 }, "required": false, "name": "status", "in": "query" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "A page of items with bounded immutable results and failures.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunItem" }, "maxItems": 100 }, "next_cursor": { "type": ["string", "null"] } }, "required": ["data", "next_cursor"] }, "example": { "data": [ { "id": "66666666-6666-4666-8666-666666666666", "run_id": "44444444-4444-4444-8444-444444444444", "retry_of_item_id": null, "resource": { "type": "invoice_import", "id": "33333333-3333-4333-8333-333333333333" }, "status": "completed", "result": { "type": "invoice_import", "outcome": "imported", "invoice_id": "55555555-5555-4555-8555-555555555555" }, "failure": null, "created_at": "2026-09-08T12:00:00.000Z", "updated_at": "2026-09-08T12:00:30.000Z", "started_at": "2026-09-08T12:00:02.000Z", "finished_at": "2026-09-08T12:00:30.000Z" } ], "next_cursor": null } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } }, "/v1/workflow-runs/{id}/items/{item_id}": { "get": { "operationId": "getWorkflowRunItem", "summary": "Get a workflow run item", "tags": ["Workflow runs"], "description": "One work item using the same representation as the collection. An item must belong to the requested run and organization. Pending items have null result and failure. Failed/cancelled items have no result. Completed/skipped items retain their typed business result independently of later invoice edits or explicit retries. Technical execution retries keep the item ID. No provider payloads or task identifiers are exposed.", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization." }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "item_id", "in": "path" } ], "security": [{ "ApiKeyBearer": [] }, { "ClerkSessionBearer": [] }], "x-watchdog-permission": "read", "x-watchdog-authentication": "organization", "responses": { "200": { "description": "One work item. Failure is a successful HTTP read with status failed and failure details.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunItem" }, "example": { "id": "66666666-6666-4666-8666-666666666666", "run_id": "44444444-4444-4444-8444-444444444444", "retry_of_item_id": null, "resource": { "type": "invoice_import", "id": "33333333-3333-4333-8333-333333333333" }, "status": "completed", "result": { "type": "invoice_import", "outcome": "imported", "invoice_id": "55555555-5555-4555-8555-555555555555" }, "failure": null, "created_at": "2026-09-08T12:00:00.000Z", "updated_at": "2026-09-08T12:00:30.000Z", "started_at": "2026-09-08T12:00:02.000Z", "finished_at": "2026-09-08T12:00:30.000Z" } } } }, "400": { "description": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_validation_error" }, "example": { "error": { "code": "validation_error", "message": "Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes).", "request_id": "req_example" } } } } }, "401": { "description": "Missing or invalid bearer credential.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "WWW-Authenticate": { "schema": { "type": "string" }, "required": false, "description": "Bearer authentication challenge, when supplied." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_invalid_token" }, "example": { "error": { "code": "invalid_token", "message": "Missing or invalid bearer credential.", "request_id": "req_example" } } } } }, "403": { "description": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required" }, "example": { "error": { "code": "forbidden", "message": "Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions.", "request_id": "req_example" } } } } }, "404": { "description": "The resource does not exist in the current organization.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_not_found" }, "example": { "error": { "code": "not_found", "message": "The resource does not exist in the current organization.", "request_id": "req_example" } } } } }, "429": { "description": "The IP or authenticated credential exceeded its request limit.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_rate_limit_exceeded" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "The IP or authenticated credential exceeded its request limit.", "request_id": "req_example" } } } } }, "500": { "description": "Unexpected server failure. Include the request ID when contacting support.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_internal_error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected server failure. Include the request ID when contacting support.", "request_id": "req_example" } } } } }, "503": { "description": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "required": true, "description": "Request identifier for support and diagnostics; also included in error bodies." }, "Cache-Control": { "schema": { "type": "string", "enum": ["private, no-store"] }, "required": false, "description": "Organization-scoped API responses must not be cached. May be absent for requests rejected before routing." }, "X-RateLimit-Limit": { "schema": { "type": "string", "example": "120" }, "required": false, "description": "Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit." }, "Retry-After": { "schema": { "type": "string", "example": "60" }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error_service_unavailable" }, "example": { "error": { "code": "service_unavailable", "message": "Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided.", "request_id": "req_example" } } } } } } } } }, "webhooks": {} }