> ## 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 > Lists agreement summaries with the requested filters. For upcoming dates, upcoming_through finds agreements whose renewal deadline (renewal_action.deadline: cancel or renew by then) or expiration date falls between today and the given date. Use next_cursor with the same filters and sorting to read more. Read an individual agreement, its documents and its prices for the full details. ## OpenAPI ````yaml /openapi.json get /v1/agreements openapi: 3.1.0 info: title: Watchdog API version: 1.0.0 description: >- The Watchdog API is served from https://api.watchdog.no. Request bodies are limited to 2 MiB unless an endpoint says otherwise. Files are uploaded directly to storage, not through the API. servers: - url: https://api.watchdog.no description: Watchdog API security: [] paths: /v1/agreements: get: tags: - Agreements summary: List agreements description: >- Lists agreement summaries with the requested filters. For upcoming dates, upcoming_through finds agreements whose renewal deadline (renewal_action.deadline: cancel or renew by then) or expiration date falls between today and the given date. Use next_cursor with the same filters and sorting to read more. Read an individual agreement, its documents and its prices for the full details. operationId: listAgreements parameters: - name: X-Organization-Id in: header required: false schema: type: string description: >- The organization to act in. Required for personal API keys; list the organizations you can access with GET /v1/organizations. - name: fields in: query required: false schema: type: string description: >- Return only these fields of each row, comma-separated; use dots for nested fields, such as suppliers.id. id is always returned. Fields: id, title, status, effective_date, expiration_date, suppliers, recipients, tags, projects, owner_user_id, owner, readiness, renewal_action, version, created_at, updated_at, alert_summary, relationships. - schema: type: string enum: - 'true' - 'false' description: >- Only records matched by the filters of teams you belong to. Teams combine with OR; other filters combine with AND. Cannot be combined with team_ids. required: false description: >- Only records matched by the filters of teams you belong to. Teams combine with OR; other filters combine with AND. Cannot be combined with team_ids. name: mine in: query - schema: type: string description: >- Only records matched by the filters of these teams: at most 50, comma-separated in a query string or an array in a JSON body. Teams combine with OR. Unknown teams return 404. required: false description: >- Only records matched by the filters of these teams: at most 50, comma-separated in a query string or an array in a JSON body. Teams combine with OR. Unknown teams return 404. name: team_ids in: query - schema: type: string description: Only these agreement IDs (maximum 50). required: false description: Only these agreement IDs (maximum 50). name: ids in: query - schema: type: string description: >- Agreements whose next renewal action is any of these kinds: cancel_by (renews automatically unless cancelled by the deadline), renew_by (ends unless renewed by the deadline), automatic_notice (renews automatically with no expiration date; it can be ended at any time with the notice period, so there is no deadline), missing_details (renewal terms exist but the deadline cannot be computed), none (does not renew, or no renewals remain). required: false description: >- Agreements whose next renewal action is any of these kinds: cancel_by (renews automatically unless cancelled by the deadline), renew_by (ends unless renewed by the deadline), automatic_notice (renews automatically with no expiration date; it can be ended at any time with the notice period, so there is no deadline), missing_details (renewal terms exist but the deadline cannot be computed), none (does not renew, or no renewals remain). name: renewal_action_kinds in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Renewal action deadline on or after this date. required: false description: Renewal action deadline on or after this date. name: renewal_deadline_from in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Renewal action deadline on or before this date. required: false description: Renewal action deadline on or before this date. name: renewal_deadline_through in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Agreements with a renewal deadline or an expiration date from today, in the organization's timezone, through this date: what must be cancelled, renewed or will end soon. required: false description: >- Agreements with a renewal deadline or an expiration date from today, in the organization's timezone, through this date: what must be cancelled, renewed or will end soon. name: upcoming_through in: query - schema: type: string minLength: 1 maxLength: 200 description: Text in the agreement title or a supplier name. required: false description: Text in the agreement title or a supplier name. name: search in: query - schema: type: string description: >- Agreements with any of these statuses: draft (being set up), active (Watchdog checks invoices against it) or archived (no longer checked). It does not say whether the contract term is in force: use expiration_date, renewal_action or the valid_on filter for that. required: false description: >- Agreements with any of these statuses: draft (being set up), active (Watchdog checks invoices against it) or archived (no longer checked). It does not say whether the contract term is in force: use expiration_date, renewal_action or the valid_on filter for that. name: statuses in: query - schema: type: string description: Agreements covering any of these suppliers. required: false description: Agreements covering any of these suppliers. name: supplier_ids in: query - schema: type: string description: >- Agreements covering any of these recipients, including agreements for any recipient. required: false description: >- Agreements covering any of these recipients, including agreements for any recipient. name: recipient_ids in: query - schema: type: string description: Agreements with any of these tags. required: false description: Agreements with any of these tags. name: tag_ids in: query - schema: type: string description: >- Any selected project. Always combined with other dimensions using AND. Unavailable IDs return 404. required: false description: >- Any selected project. Always combined with other dimensions using AND. Unavailable IDs return 404. name: project_ids in: query - schema: type: string description: >- Any selected owner. IDs are case-sensitive. Unavailable members return 404. required: false description: >- Any selected owner. IDs are case-sensitive. Unavailable members return 404. name: owner_user_ids in: query - schema: type: string enum: - is - is_not required: false name: supplier_operator in: query - schema: type: string enum: - is - is_not required: false name: tag_operator in: query - schema: type: string enum: - and - or description: >- Combine supplier and tag ID filters with AND (default) or OR. Other filters and the organization boundary always apply. required: false description: >- Combine supplier and tag ID filters with AND (default) or OR. Other filters and the organization boundary always apply. name: join_operator in: query - schema: type: string description: >- Agreements with at least one alert with any of these verdicts. Combine with has_alert_credited to match both on the same alert. Comma-separated: pending, accepted, dismissed. required: false description: >- Agreements with at least one alert with any of these verdicts. Combine with has_alert_credited to match both on the same alert. Comma-separated: pending, accepted, dismissed. name: has_alert_verdicts in: query - schema: type: string enum: - 'true' - 'false' description: >- Agreements with at least one alert that is (true) or is not (false) credited. required: false description: >- Agreements with at least one alert that is (true) or is not (false) credited. name: has_alert_credited in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Effective (start) date on or after this date; excludes agreements without one. required: false description: >- Effective (start) date on or after this date; excludes agreements without one. name: effective_from in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Effective (start) date on or before this date; excludes agreements without one. required: false description: >- Effective (start) date on or before this date; excludes agreements without one. name: effective_through in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Expiration date on or after this date; excludes agreements without one. required: false description: >- Expiration date on or after this date; excludes agreements without one. name: expiration_from in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Expiration date on or before this date; excludes agreements without one. required: false description: >- Expiration date on or before this date; excludes agreements without one. name: expiration_through in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Agreements in force on this date: effective on or before it and expiring on or after it. A missing effective or expiration date counts as open-ended. required: false description: >- Agreements in force on this date: effective on or before it and expiring on or after it. A missing effective or expiration date counts as open-ended. name: valid_on in: query - schema: type: integer minimum: 1 maximum: 1000 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 - status - renewal_deadline - title - effective_date - expiration_date - supplier - pending_topic_count - alert_progress - open_alert_impact default: created_at description: >- alert_progress is the share of alerts that are no longer pending. open_alert_impact is the pending and claimed impact in the organization currency. required: false description: >- alert_progress is the share of alerts that are no longer pending. open_alert_impact is the 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: A page of agreements. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AgreementSummary' maxItems: 1000 next_cursor: type: - string - 'null' required: - data - next_cursor '400': description: >- The request is invalid. details lists up to 20 field errors. Request bodies are limited to 2 MiB. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: $ref: '#/components/schemas/Error_validation_error' example: error: code: validation_error message: >- The request is invalid. details lists up to 20 field errors. Request bodies are limited to 2 MiB. request_id: req_example '401': description: The bearer token is missing or invalid. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. 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: The bearer token is missing or invalid. request_id: req_example '403': description: >- Access denied. The error code says why: forbidden, token_disabled, organization_required, insufficient_role or mfa_required. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: $ref: >- #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required example: error: code: forbidden message: >- Access denied. The error code says why: forbidden, token_disabled, organization_required, insufficient_role or mfa_required. 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 ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. 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 ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. 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: Too many requests. Wait for the Retry-After delay before retrying. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. Retry-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: >- Too many requests. Wait for the Retry-After delay before retrying. 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 ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. 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: >- Temporarily unavailable. Retry after the Retry-After delay, when provided. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. Retry-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: >- Temporarily unavailable. Retry after the Retry-After delay, when provided. request_id: req_example security: - ApiKeyBearer: [] components: schemas: AgreementSummary: type: object properties: id: type: string format: uuid title: type: - string - 'null' status: type: string enum: - draft - active - archived description: >- draft (being set up), active (Watchdog checks invoices against it) or archived (no longer checked). It does not say whether the contract term is in force: use expiration_date, renewal_action or the valid_on filter for that. 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: Suppliers the agreement covers. 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: Recipients the agreement covers. 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: Assigned tags. example: [] projects: type: array items: type: object properties: id: type: string format: uuid name: type: string project_numbers: type: array items: type: string required: - id - name - project_numbers owner_user_id: type: - string - 'null' minLength: 1 maxLength: 200 pattern: ^[A-Za-z0-9_-]+$ owner: type: - object - 'null' properties: user_id: type: string minLength: 1 maxLength: 200 pattern: ^[A-Za-z0-9_-]+$ first_name: type: - string - 'null' last_name: type: - string - 'null' email: type: - string - 'null' required: - user_id - first_name - last_name - email readiness: type: object properties: ready: type: boolean reasons: type: array items: type: string enum: - inactive - missing_title - missing_supplier - missing_content - documents_not_ready required: - ready - reasons description: >- Whether the agreement can be checked. reasons lists what is missing when ready is false. renewal_action: oneOf: - type: object properties: kind: type: string enum: - cancel_by deadline: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: - kind - deadline - type: object properties: kind: type: string enum: - renew_by deadline: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: - kind - deadline - type: object properties: kind: type: string enum: - automatic_notice deadline: type: 'null' notice: type: object properties: value: type: integer unit: type: string enum: - days - weeks - months - years required: - value - unit required: - kind - deadline - notice - type: object properties: kind: type: string enum: - missing_details deadline: type: 'null' required: - kind - deadline - type: object properties: kind: type: string enum: - none deadline: type: 'null' required: - kind - deadline description: >- The next renewal action from the renewal terms. A null deadline means no dated action is known. 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: object properties: credited: type: integer minimum: 0 uncredited: type: integer minimum: 0 required: - credited - uncredited accepted: type: object properties: credited: type: integer minimum: 0 uncredited: type: integer minimum: 0 required: - credited - uncredited dismissed: type: object properties: credited: type: integer minimum: 0 uncredited: type: integer minimum: 0 required: - credited - uncredited required: - pending - accepted - dismissed description: >- Alerts by verdict, each split into credited and uncredited alerts. pending_topic_count: type: integer minimum: 0 description: >- Topics with at least one pending, uncredited alert. 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+)?$ by_verdict: type: object properties: pending: type: object properties: credited: type: object properties: alert_count: type: integer impact_amount: type: string pattern: ^-?\d+(?:\.\d+)?$ description: >- Sum of the alerts’ impacts; alerts without an impact add nothing. required: - alert_count - impact_amount uncredited: type: object properties: alert_count: type: integer impact_amount: type: string pattern: ^-?\d+(?:\.\d+)?$ description: >- Sum of the alerts’ impacts; alerts without an impact add nothing. required: - alert_count - impact_amount required: - credited - uncredited accepted: type: object properties: credited: type: object properties: alert_count: type: integer impact_amount: type: string pattern: ^-?\d+(?:\.\d+)?$ description: >- Sum of the alerts’ impacts; alerts without an impact add nothing. required: - alert_count - impact_amount uncredited: type: object properties: alert_count: type: integer impact_amount: type: string pattern: ^-?\d+(?:\.\d+)?$ description: >- Sum of the alerts’ impacts; alerts without an impact add nothing. required: - alert_count - impact_amount required: - credited - uncredited dismissed: type: object properties: credited: type: object properties: alert_count: type: integer impact_amount: type: string pattern: ^-?\d+(?:\.\d+)?$ description: >- Sum of the alerts’ impacts; alerts without an impact add nothing. required: - alert_count - impact_amount uncredited: type: object properties: alert_count: type: integer impact_amount: type: string pattern: ^-?\d+(?:\.\d+)?$ description: >- Sum of the alerts’ impacts; alerts without an impact add nothing. required: - alert_count - impact_amount required: - credited - uncredited required: - pending - accepted - dismissed description: >- Counts and impact by verdict, each split into credited and uncredited alerts. required: - currency_code - impact_amount - by_verdict description: >- Impact in the organization currency: the sum of the alerts’ converted impacts. required: - counts - pending_topic_count - organization_currency description: >- All alerts of this agreement, as GET /v1/alerts/metrics?agreement_ids={id} reports them. 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: Invoices currently matched to this agreement. supplier_invoice_count: type: integer minimum: 0 description: >- Invoices from this agreement's suppliers, before other matching conditions apply. required: - price_item_count - document_count - invoice_match_count - supplier_invoice_count required: - id - title - status - effective_date - expiration_date - suppliers - recipients - tags - projects - owner_user_id - owner - readiness - renewal_action - 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_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 sent as a bearer token, together with X-Organization-Id. The key must have at least the access level the endpoint requires (read, write or admin). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.