> ## 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.

# Edit an agreement

> 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.



## OpenAPI

````yaml /openapi-preview.json patch /v1/agreements/{id}
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/{id}:
    patch:
      tags:
        - Agreements
      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.
      operationId: updateAgreement
      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
      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
      security:
        - ApiKeyBearer: []
        - ClerkSessionBearer: []
components:
  schemas:
    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_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_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
    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
    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
  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.

````