> ## Documentation Index > Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt > Use this file to discover all available pages before exploring further. # List alerts > 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. ## OpenAPI ````yaml /openapi-preview.json get /v1/alerts 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 security: [] paths: /v1/alerts: get: tags: - Alerts summary: List 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. operationId: listAlerts 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 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 security: - ApiKeyBearer: [] - ClerkSessionBearer: [] components: schemas: 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 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_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 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 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. ````