> ## 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 agreements ## OpenAPI ````yaml /openapi-preview.json get /v1/agreements 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/agreements: get: tags: - Agreements summary: List agreements operationId: listAgreements 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 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 security: - ApiKeyBearer: [] - ClerkSessionBearer: [] components: schemas: 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 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_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 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. ````