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

# Update an alert: edit, confirm, mark as false alarm, skip, move back to review, add to a claim, move to another topic

> Send only the fields to change, with the same names and nesting as GET; omitted fields are kept and null clears a field. verdict, dismissal, claim_id and topic_id work as in POST /v1/alerts/update. Only the fields you send change, and each changes only itself: setting a claim does not confirm, a verdict does not touch claims or credit. A false alarm (verdict dismissed) needs a dismissal category and starts a run that suggests improvements to the agreement's instructions, unless suggest_instructions is false; once no alert keeps that false alarm, because its alerts took another verdict or a new reason, its suggestions nobody has reviewed are withdrawn. A claim can hold alerts of any verdict but asks only for accepted ones. To stop Watchdog flagging a kind of deviation again, teach the agreement a rule with POST /v1/agreements/{id}/teach. expected.net_price, expected.total, invoiced, invoice_item and provenance are read-only. confidence takes level and reason. citations takes upsert and remove changes by source_ref.



## OpenAPI

````yaml /openapi.json patch /v1/alerts/{id}
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/alerts/{id}:
    patch:
      tags:
        - Alerts
      summary: >-
        Update an alert: edit, confirm, mark as false alarm, skip, move back to
        review, add to a claim, move to another topic
      description: >-
        Send only the fields to change, with the same names and nesting as GET;
        omitted fields are kept and null clears a field. verdict, dismissal,
        claim_id and topic_id work as in POST /v1/alerts/update. Only the fields
        you send change, and each changes only itself: setting a claim does not
        confirm, a verdict does not touch claims or credit. A false alarm
        (verdict dismissed) needs a dismissal category and starts a run that
        suggests improvements to the agreement's instructions, unless
        suggest_instructions is false; once no alert keeps that false alarm,
        because its alerts took another verdict or a new reason, its suggestions
        nobody has reviewed are withdrawn. A claim can hold alerts of any
        verdict but asks only for accepted ones. To stop Watchdog flagging a
        kind of deviation again, teach the agreement a rule with POST
        /v1/agreements/{id}/teach. expected.net_price, expected.total, invoiced,
        invoice_item and provenance are read-only. confidence takes level and
        reason. citations takes upsert and remove changes by source_ref.
      operationId: updateAlert
      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.
        - schema:
            type: string
            format: uuid
          required: true
          name: id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                citations:
                  $ref: '#/components/schemas/AlertCitationChanges'
                title:
                  type: string
                  minLength: 1
                  maxLength: 500
                explanation:
                  type:
                    - string
                    - 'null'
                  maxLength: 20000
                questions:
                  type: array
                  items:
                    type: string
                    maxLength: 2000
                  maxItems: 50
                impact_amount:
                  type:
                    - string
                    - 'null'
                  maxLength: 100
                  pattern: ^-?\d+(?:\.\d+)?$
                  description: >-
                    The remaining impact in the invoice currency after assessed
                    credits. Positive means still owed. Pricing edits leave it
                    unchanged; send impact_amount explicitly to change it.
                confidence:
                  type: object
                  properties:
                    level:
                      type:
                        - string
                        - 'null'
                      enum:
                        - certain
                        - uncertain
                        - null
                    reason:
                      type:
                        - string
                        - 'null'
                      maxLength: 2000
                  additionalProperties: false
                expected:
                  type: object
                  properties:
                    base_price:
                      type:
                        - string
                        - 'null'
                      maxLength: 100
                      pattern: ^-?\d+(?:\.\d+)?$
                    quantity:
                      type:
                        - string
                        - 'null'
                      maxLength: 100
                      pattern: ^-?\d+(?:\.\d+)?$
                    discount:
                      type:
                        - string
                        - 'null'
                      maxLength: 100
                      pattern: ^-?\d+(?:\.\d+)?$
                    surcharge:
                      type:
                        - string
                        - 'null'
                      maxLength: 100
                      pattern: ^-?\d+(?:\.\d+)?$
                    adjustment_uplift:
                      type:
                        - string
                        - 'null'
                      maxLength: 100
                      pattern: ^-?\d+(?:\.\d+)?$
                    price_explanation:
                      type:
                        - string
                        - 'null'
                      maxLength: 20000
                    adjustment_explanation:
                      type:
                        - string
                        - 'null'
                      maxLength: 20000
                    product_code:
                      type:
                        - string
                        - 'null'
                      maxLength: 2000
                    description:
                      type:
                        - string
                        - 'null'
                      maxLength: 20000
                    unit:
                      type:
                        - string
                        - 'null'
                      maxLength: 2000
                  additionalProperties: false
                verdict:
                  type: string
                  enum:
                    - pending
                    - accepted
                    - dismissed
                    - skipped
                  description: >-
                    Whether the finding is right. pending: still to review.
                    accepted: confirmed, the deviation is real (also when it is
                    too small to pursue or already handled). dismissed: a false
                    alarm, Watchdog was wrong; requires dismissal with a
                    category. skipped (shown as Unsure): nobody can or will
                    judge it; it leaves review without teaching anything. Claim
                    membership and credit are not changed. Leaving dismissed
                    takes the dismissal off the alert; it stays in the history.
                dismissal:
                  type: object
                  properties:
                    category:
                      type: string
                      enum:
                        - misread
                        - missing_context
                        - duplicate
                        - other
                      description: >-
                        Why Watchdog was wrong. misread: it misread the
                        agreement or the invoice. missing_context: it lacked
                        information it could not see, such as a side agreement
                        or a price change agreed by email. duplicate: it flagged
                        the same deviation twice. other: explain in note. An
                        alert that is right but not worth pursuing, or already
                        handled, is confirmed (accepted), not a false alarm.
                    note:
                      type:
                        - string
                        - 'null'
                      maxLength: 2000
                      description: >-
                        What Watchdog got wrong, in your own words. Required
                        with category other.
                  required:
                    - category
                  additionalProperties: false
                  description: >-
                    Why the alerts are false alarms. Required with verdict
                    dismissed, and only valid with it. Sending a different
                    reason for an already dismissed alert replaces its reason.
                suggest_instructions:
                  type: boolean
                  description: >-
                    Whether the false alarm should start a run that suggests
                    changes to the agreement's instructions, so later checks
                    avoid the mistake. Defaults to true. Send false when the
                    note explains a cleanup rather than a rule for future
                    checks. Only valid with verdict dismissed; it is not stored
                    on the alert.
                claim_id:
                  type:
                    - string
                    - 'null'
                  format: uuid
                  description: >-
                    Put the alerts in this pending or in-progress claim of their
                    agreement, or null to take them out of their claim. Verdicts
                    are not changed: send verdict accepted to accept them too.
                    Alerts move out of a cancelled claim; out of another open
                    claim only with move_from_open_claims. Alerts in completed
                    claims cannot be changed. POST /v1/claims/alerts/preview
                    says first which alerts would join and why the others would
                    not.
                move_from_open_claims:
                  type: boolean
                  description: >-
                    Move alerts out of other pending or in-progress claims. Only
                    valid with a claim_id.
                topic_id:
                  type:
                    - string
                    - 'null'
                  format: uuid
                  description: >-
                    Move the alerts into this topic of their agreement, out of
                    any other topic, or null to take them out of their topic.
                    Categorization may later place an alert without a topic in
                    one again.
              additionalProperties: false
      responses:
        '200':
          description: The alert.
          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/Alert'
        '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:
              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
              schema:
                $ref: '#/components/schemas/Error_validation_error'
        '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:
              example:
                error:
                  code: invalid_token
                  message: The bearer token is missing or invalid.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_invalid_token'
        '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:
              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
              schema:
                $ref: >-
                  #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required
        '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:
              example:
                error:
                  code: not_found
                  message: The resource does not exist in the current organization.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_not_found'
        '409':
          description: >-
            The alert belongs to a completed claim or another open claim, or
            this change is incompatible with it.
          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:
              example:
                error:
                  code: conflict
                  message: >-
                    The alert belongs to a completed claim or another open
                    claim, or this change is incompatible with it.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_conflict'
        '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:
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Too many requests. Wait for the Retry-After delay before
                    retrying.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_rate_limit_exceeded'
        '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:
              example:
                error:
                  code: internal_error
                  message: >-
                    Unexpected server failure. Include the request ID when
                    contacting support.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_internal_error'
        '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:
              example:
                error:
                  code: service_unavailable
                  message: >-
                    Temporarily unavailable. Retry after the Retry-After delay,
                    when provided.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_service_unavailable'
      security:
        - ApiKeyBearer: []
components:
  schemas:
    AlertCitationChanges:
      type: object
      properties:
        upsert:
          type: array
          items:
            type: object
            properties:
              source_ref:
                type: integer
                exclusiveMinimum: 0
                maximum: 2147483647
              source:
                $ref: '#/components/schemas/CitationSourceInput'
              quote:
                type:
                  - string
                  - 'null'
                maxLength: 20000
              text:
                type:
                  - string
                  - 'null'
                maxLength: 20000
              section_title:
                type:
                  - string
                  - 'null'
                maxLength: 20000
              context_before:
                type:
                  - string
                  - 'null'
                maxLength: 20000
              context_after:
                type:
                  - string
                  - 'null'
                maxLength: 20000
              title:
                type:
                  - string
                  - 'null'
                maxLength: 20000
              citation:
                anyOf:
                  - type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                    required:
                      - id
                    additionalProperties: false
                  - type: object
                    properties:
                      source:
                        $ref: '#/components/schemas/CitationSourceInput'
                      quote:
                        type:
                          - string
                          - 'null'
                        maxLength: 20000
                      text:
                        type:
                          - string
                          - 'null'
                        maxLength: 20000
                      section_title:
                        type:
                          - string
                          - 'null'
                        maxLength: 20000
                      context_before:
                        type:
                          - string
                          - 'null'
                        maxLength: 20000
                      context_after:
                        type:
                          - string
                          - 'null'
                        maxLength: 20000
                      title:
                        type:
                          - string
                          - 'null'
                        maxLength: 20000
                    required:
                      - source
                    additionalProperties: false
            required:
              - source_ref
            additionalProperties: false
          maxItems: 100
          default: []
        remove:
          type: array
          items:
            type: integer
            exclusiveMinimum: 0
            maximum: 2147483647
          maxItems: 100
          default: []
      additionalProperties: false
      description: >-
        Changes to the alert's citations, by source_ref: upsert edits a
        citation's fields, or points the reference at an existing citation by id
        or a new one; remove drops references.
    Alert:
      allOf:
        - $ref: '#/components/schemas/AlertSummary'
        - type: object
          properties:
            price_item_ids:
              type: array
              items:
                type: string
                format: uuid
              description: >-
                Agreement prices the alert relies on. Read them with GET
                /v1/agreements/{id}/price-items?ids=. Empty when you cannot see
                the agreement.
            expected:
              type: object
              properties:
                base_price:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                quantity:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                discount:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                surcharge:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                adjustment_uplift:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                net_price:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                  readOnly: true
                  description: Calculated from the expected pricing fields.
                total:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                  readOnly: true
                  description: Calculated from expected net price and quantity.
                price_explanation:
                  type:
                    - string
                    - 'null'
                adjustment_explanation:
                  type:
                    - string
                    - 'null'
                product_code:
                  type:
                    - string
                    - 'null'
                description:
                  type:
                    - string
                    - 'null'
                unit:
                  type:
                    - string
                    - 'null'
              required:
                - base_price
                - quantity
                - discount
                - surcharge
                - adjustment_uplift
                - net_price
                - total
                - price_explanation
                - adjustment_explanation
                - product_code
                - description
                - unit
              description: >-
                The pricing the check's baseline gives for this line: the
                agreement's, as the check applied it, or the purchase order
                line's net price and ordered quantity. base_price is the agreed
                unit price before discount and surcharge; price_explanation says
                where it comes from. Every field of an agreement alert is null
                when you cannot see its agreement; a purchase-order alert is
                visible only with its order.
            invoiced:
              type: object
              properties:
                base_price:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                net_price:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                quantity:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                discount:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                surcharge:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
                total:
                  type:
                    - string
                    - 'null'
                  pattern: ^-?\d+(?:\.\d+)?$
              required:
                - base_price
                - net_price
                - quantity
                - discount
                - surcharge
                - total
              readOnly: true
              description: Invoiced pricing when the alert was created.
            evidence:
              $ref: '#/components/schemas/CitationEvidence'
          required:
            - price_item_ids
            - expected
            - invoiced
            - evidence
    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
    CitationSourceInput:
      anyOf:
        - type: object
          properties:
            source_type:
              type: string
              enum:
                - document
            document_id:
              type: string
              format: uuid
          required:
            - source_type
            - document_id
          additionalProperties: false
        - type: object
          properties:
            source_type:
              type: string
              enum:
                - web
            url:
              type: string
              maxLength: 20000
          required:
            - source_type
            - url
          additionalProperties: false
        - type: object
          properties:
            source_type:
              type: string
              enum:
                - agreement_items
            item_ids:
              type: array
              items:
                type: string
                format: uuid
              minItems: 1
              maxItems: 100
          required:
            - source_type
            - item_ids
          additionalProperties: false
        - type: object
          properties:
            source_type:
              type: string
              enum:
                - user_context
            text:
              type: string
              minLength: 1
              maxLength: 20000
          required:
            - source_type
            - text
          additionalProperties: false
    AlertSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        check_type:
          type: string
          enum:
            - agreement
            - purchase_order
            - duplicate
          description: >-
            The type of invoice check the alert belongs to. Alerts of an
            agreement check have an agreement, alerts of a purchase-order check
            a purchase order; never both; duplicate alerts neither.
        code:
          type:
            - string
            - 'null'
          enum:
            - unit_price
            - quantity
            - received
            - vat_rate
            - unordered_charge
            - unbilled_discount
            - amount_limit
            - uncertain
            - different_total
            - different_date
            - other_company
            - null
          description: >-
            The named finding of a purchase-order check (unit_price, quantity,
            received: billed above what was received, vat_rate: a higher VAT
            rate than the order line states, unordered_charge,
            unbilled_discount: an order discount the invoices leave out,
            amount_limit: the order's running total, uncertain) or duplicate
            check (different_total, different_date: another invoice of the
            supplier with the same number; other_company: the same number, date
            and total received by another of the workspace's companies); the
            explanation says what it found. Null on agreement alerts.
        details:
          $ref: '#/components/schemas/AlertFindingDetails'
        title:
          type:
            - string
            - 'null'
        explanation:
          type:
            - string
            - 'null'
        verdict:
          type: string
          enum:
            - pending
            - accepted
            - dismissed
            - skipped
          description: >-
            Whether the finding is right: pending (still to review), accepted
            (confirmed), dismissed (a false alarm) or skipped (unsure).
            Independent of claim membership and credit.
        credit:
          type:
            - object
            - 'null'
          properties:
            at:
              type: string
              format: date-time
            source:
              type: string
              enum:
                - credit_note
            credit_note_id:
              type:
                - string
                - 'null'
              format: uuid
              description: The matched credit note. Null when you cannot see it.
          required:
            - at
            - source
            - credit_note_id
          description: >-
            Set while a matched credit note fully reverses the invoice; it
            cannot be set by hand. Independent of the verdict and claim.
        correction_type:
          type: string
          enum:
            - modify_item
            - modify_invoice
            - add_item
        confidence:
          type: object
          properties:
            level:
              type:
                - string
                - 'null'
              enum:
                - certain
                - uncertain
                - null
            reason:
              type:
                - string
                - 'null'
          required:
            - level
            - reason
        questions:
          type: array
          items:
            type: string
          description: >-
            What Watchdog needs answered to decide the alert, mostly on
            uncertain alerts. Empty when nothing is open.
        impact_amount:
          type:
            - string
            - 'null'
          pattern: ^-?\d+(?:\.\d+)?$
          description: >-
            The remaining impact in the invoice currency, after credit notes
            assessed by the check. Expected pricing stays at the agreement
            terms. Pricing edits preserve impact unless it is explicitly
            changed.
        currency_code:
          type: string
        organization_currency:
          type: object
          properties:
            currency_code:
              type: string
              description: The organization's reporting currency from its settings.
            impact_amount:
              type:
                - string
                - 'null'
              pattern: ^-?\d+(?:\.\d+)?$
          required:
            - currency_code
            - impact_amount
          description: The impact converted with the rate stored on the alert.
        invalidation:
          type:
            - object
            - 'null'
          properties:
            at:
              type: string
              format: date-time
            reason:
              type: string
              enum:
                - unmatched
                - replaced
                - excluded
          required:
            - at
            - reason
          description: >-
            Set when the alert no longer counts. unmatched: its invoice no
            longer matches the agreement; excluded: a person excluded the
            invoice from it. Both count again once it matches again. replaced: a
            re-check of its pair replaced it with new alerts; it stays for
            reference. It keeps its verdict, credit and claim either way.
        invoice:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            invoice_number:
              type:
                - string
                - 'null'
            title:
              type:
                - string
                - 'null'
              description: The invoice's own title; its number is invoice_number.
            category:
              type: string
              enum:
                - invoice
                - credit_note
                - self_billed_invoice
                - reminder
                - collection_notice
            issued_date:
              type:
                - string
                - 'null'
              format: date
            due_date:
              type:
                - string
                - 'null'
              format: date
            currency_code:
              type:
                - string
                - 'null'
            total_amount_including_vat:
              type:
                - string
                - 'null'
              pattern: ^-?\d+(?:\.\d+)?$
          required:
            - id
            - invoice_number
            - title
            - category
            - issued_date
            - due_date
            - currency_code
            - total_amount_including_vat
        invoice_item:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            line_number:
              type: integer
            product_code:
              type:
                - string
                - 'null'
            description:
              type:
                - string
                - 'null'
            unit:
              type:
                - string
                - 'null'
          required:
            - id
            - line_number
            - product_code
            - description
            - unit
          readOnly: true
          description: The current invoice line. Null when no line is linked.
        agreement:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            title:
              type:
                - string
                - 'null'
            status:
              type: string
              enum:
                - draft
                - active
                - archived
            version:
              type: integer
              description: The current agreement version.
          required:
            - id
            - title
            - status
            - version
          description: >-
            The agreement the alert was found against. Null when you cannot see
            it, or when the alert belongs to a check type without an agreement.
        purchase_order:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            number:
              type:
                - string
                - 'null'
          required:
            - id
            - number
          description: >-
            The purchase order a purchase-order check found the alert against.
            Never the agreement that order is linked to.
        supplier:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            title:
              type:
                - string
                - 'null'
          required:
            - id
            - title
        recipient:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            title:
              type:
                - string
                - 'null'
          required:
            - id
            - title
        topic:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            title:
              type:
                - string
                - 'null'
            is_locked:
              type: boolean
          required:
            - id
            - title
            - is_locked
        claim:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            title:
              type:
                - string
                - 'null'
            status:
              type: string
              enum:
                - pending
                - in_progress
                - completed
                - cancelled
          required:
            - id
            - title
            - status
          description: The claim this alert is currently attached to, if any.
        dismissal:
          $ref: '#/components/schemas/AlertDismissal'
        provenance:
          $ref: '#/components/schemas/AlertProvenance'
        correction_relationships:
          type: array
          items:
            type: object
            properties:
              replacement_alert_id:
                type: string
                format: uuid
              replaced_alert_id:
                type: string
                format: uuid
            required:
              - replacement_alert_id
              - replaced_alert_id
          maxItems: 100
          description: Links between an added-item alert and the line alerts it replaces.
        correction_relationships_truncated:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - check_type
        - code
        - details
        - title
        - explanation
        - verdict
        - credit
        - correction_type
        - confidence
        - questions
        - impact_amount
        - currency_code
        - organization_currency
        - invalidation
        - invoice
        - invoice_item
        - agreement
        - purchase_order
        - supplier
        - recipient
        - topic
        - claim
        - dismissal
        - provenance
        - correction_relationships
        - correction_relationships_truncated
        - created_at
        - updated_at
    CitationEvidence:
      type: object
      properties:
        citations:
          type: array
          items:
            anyOf:
              - type: object
                properties:
                  source_ref:
                    type: integer
                    exclusiveMinimum: 0
                  citation_id:
                    type:
                      - string
                      - 'null'
                    format: uuid
                  available:
                    type: boolean
                    enum:
                      - true
                  source_type:
                    type: string
                    enum:
                      - document
                  document_id:
                    type: string
                    format: uuid
                  document_name:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                  section_title:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                  quote:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                    description: >-
                      The cited text as found in the document. Null when only
                      context_before and context_after locate it.
                  context_before:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                    description: Only with citation_context=true.
                  context_after:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                    description: Only with citation_context=true.
                  verification:
                    type:
                      - string
                      - 'null'
                    enum:
                      - verified
                      - corrected
                      - recovered
                      - unverified
                      - null
                    description: >-
                      verified: the quote was found in the document. corrected:
                      found after fixing the document or wording. recovered:
                      located by its context only. unverified: not found.
                  original_quote:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                    description: >-
                      The check's wording when the quote was not found verbatim
                      (quote is null); null otherwise.
                required:
                  - source_ref
                  - citation_id
                  - available
                  - source_type
                  - document_id
                  - document_name
                  - section_title
                  - quote
                  - verification
                  - original_quote
              - type: object
                properties:
                  source_ref:
                    type: integer
                    exclusiveMinimum: 0
                  citation_id:
                    type:
                      - string
                      - 'null'
                    format: uuid
                  available:
                    type: boolean
                    enum:
                      - true
                  source_type:
                    type: string
                    enum:
                      - web
                  url:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                  title:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                  quote:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                  text:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                  cited_at:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                required:
                  - source_ref
                  - citation_id
                  - available
                  - source_type
                  - url
                  - title
                  - quote
                  - text
                  - cited_at
              - type: object
                properties:
                  source_ref:
                    type: integer
                    exclusiveMinimum: 0
                  citation_id:
                    type:
                      - string
                      - 'null'
                    format: uuid
                  available:
                    type: boolean
                    enum:
                      - true
                  source_type:
                    type: string
                    enum:
                      - agreement_items
                  item_ids:
                    type: array
                    items:
                      type: string
                      format: uuid
                required:
                  - source_ref
                  - citation_id
                  - available
                  - source_type
                  - item_ids
              - type: object
                properties:
                  source_ref:
                    type: integer
                    exclusiveMinimum: 0
                  citation_id:
                    type:
                      - string
                      - 'null'
                    format: uuid
                  available:
                    type: boolean
                    enum:
                      - true
                  source_type:
                    type: string
                    enum:
                      - user_context
                  text:
                    type:
                      - string
                      - 'null'
                    maxLength: 10000
                required:
                  - source_ref
                  - citation_id
                  - available
                  - source_type
                  - text
              - type: object
                properties:
                  source_ref:
                    type:
                      - integer
                      - 'null'
                    exclusiveMinimum: 0
                  citation_id:
                    type:
                      - string
                      - 'null'
                    format: uuid
                  source_type:
                    type:
                      - string
                      - 'null'
                  available:
                    type: boolean
                    enum:
                      - false
                  reason:
                    type: string
                    enum:
                      - source_unavailable
                required:
                  - source_ref
                  - citation_id
                  - source_type
                  - available
                  - reason
        truncated:
          type: boolean
          description: True when excerpts were cut at 10,000 characters.
      required:
        - citations
        - truncated
    AlertFindingDetails:
      anyOf:
        - type: object
          properties:
            code:
              type: string
              enum:
                - unit_price
            purchase_order_line_id:
              type: string
              format: uuid
            line_reference:
              type: string
            expected_unit_price:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            invoiced_unit_price:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            quantity:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            grouped:
              type: boolean
            lines:
              type: array
              items:
                type: object
                properties:
                  line_reference:
                    type: string
                  impact:
                    type: string
                    pattern: ^-?\d+(?:\.\d+)?$
                required:
                  - line_reference
                  - impact
          required:
            - code
            - purchase_order_line_id
            - line_reference
            - expected_unit_price
            - invoiced_unit_price
            - quantity
        - type: object
          properties:
            code:
              type: string
              enum:
                - quantity
            purchase_order_line_id:
              type: string
              format: uuid
            line_reference:
              type: string
            ordered_quantity:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            billed_before:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            billed_through:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            excess_quantity:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            unit_price:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            lines:
              type: array
              items:
                type: object
                properties:
                  line_reference:
                    type: string
                  impact:
                    type: string
                    pattern: ^-?\d+(?:\.\d+)?$
                required:
                  - line_reference
                  - impact
          required:
            - code
            - purchase_order_line_id
            - line_reference
            - ordered_quantity
            - billed_before
            - billed_through
            - excess_quantity
            - unit_price
        - type: object
          properties:
            code:
              type: string
              enum:
                - received
            purchase_order_line_id:
              type: string
              format: uuid
            line_reference:
              type: string
            received_quantity:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            ordered_quantity:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            billed_before:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            billed_through:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            excess_quantity:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            unit_price:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            lines:
              type: array
              items:
                type: object
                properties:
                  line_reference:
                    type: string
                  impact:
                    type: string
                    pattern: ^-?\d+(?:\.\d+)?$
                required:
                  - line_reference
                  - impact
          required:
            - code
            - purchase_order_line_id
            - line_reference
            - received_quantity
            - ordered_quantity
            - billed_before
            - billed_through
            - excess_quantity
            - unit_price
        - type: object
          properties:
            code:
              type: string
              enum:
                - vat_rate
            purchase_order_line_id:
              type: string
              format: uuid
            line_reference:
              type: string
            ordered_vat_rate:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            invoiced_vat_rate:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            amount:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            lines:
              type: array
              items:
                type: object
                properties:
                  line_reference:
                    type: string
                  impact:
                    type: string
                    pattern: ^-?\d+(?:\.\d+)?$
                required:
                  - line_reference
                  - impact
          required:
            - code
            - purchase_order_line_id
            - line_reference
            - ordered_vat_rate
            - invoiced_vat_rate
            - amount
        - type: object
          properties:
            code:
              type: string
              enum:
                - unordered_charge
            amount:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            accepted:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
          required:
            - code
            - amount
        - type: object
          properties:
            code:
              type: string
              enum:
                - unbilled_discount
            purchase_order_line_id:
              type: string
              format: uuid
            line_reference:
              type: string
            discount_amount:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            offset_by_invoices:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            remaining_amount:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
          required:
            - code
            - purchase_order_line_id
            - line_reference
            - discount_amount
            - offset_by_invoices
            - remaining_amount
        - type: object
          properties:
            code:
              type: string
              enum:
                - amount_limit
            commitment:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            billed_before:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            billed_through:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            additional_excess:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
            explained_by_lines:
              type: string
              pattern: ^-?\d+(?:\.\d+)?$
          required:
            - code
            - commitment
            - billed_before
            - billed_through
            - additional_excess
            - explained_by_lines
        - type: object
          properties:
            code:
              type: string
              enum:
                - uncertain
            reasons:
              type: array
              items:
                type: object
                properties:
                  reason:
                    type: string
                    enum:
                      - tax_unknown
                      - currency_mismatch
                      - unit_mismatch
                      - lines_not_tied
                      - lines_unassigned
                      - group_inexact
                      - pending_suggestions
                      - incompatible_invoices
                      - invalid_invoices
                      - unsupported_credits
                      - unassigned_invoices
                  invoice_item_ids:
                    type: array
                    items:
                      type: string
                      format: uuid
                    default: []
                  count:
                    type:
                      - integer
                      - 'null'
                    minimum: 0
                    default: null
                required:
                  - reason
              minItems: 1
          required:
            - code
            - reasons
        - type: object
          properties:
            code:
              type: string
              enum:
                - different_total
                - different_date
                - other_company
            invoice_id:
              type: string
              format: uuid
          required:
            - code
            - invoice_id
        - type: 'null'
      description: >-
        A purchase-order finding's compared values, one shape per code; price
        and quantity findings also fill expected and invoiced. A duplicate
        finding's other invoice_id. Null on agreement alerts, whose explanation
        names the values, and on a duplicate alert whose other invoice you
        cannot see.
    AlertDismissal:
      type:
        - object
        - 'null'
      properties:
        id:
          type: string
          format: uuid
          description: Alerts dismissed together with the same reason share this ID.
        category:
          type: string
          enum:
            - misread
            - missing_context
            - duplicate
            - other
        note:
          type:
            - string
            - 'null'
        dismissed_at:
          type: string
          format: date-time
        dismissed_by:
          $ref: '#/components/schemas/AlertActor'
      required:
        - id
        - category
        - note
        - dismissed_at
        - dismissed_by
      description: >-
        Why the alert is a false alarm, while its verdict is dismissed, credited
        or not; dismissed_by is null when no person is recorded. Dismiss it
        again with a different category or note to change the reason. Any other
        verdict clears it; the alert activity keeps the history.
    AlertProvenance:
      type: object
      properties:
        origin:
          type: string
          enum:
            - check
            - user
            - api_key
          description: >-
            Who created the alert: a compliance check (created_by null), a
            person, or a person through an API key.
        created_by:
          $ref: '#/components/schemas/AlertActor'
        agreement_version:
          type:
            - integer
            - 'null'
          description: The agreement version assessed; compare with agreement.version.
        invoice_fingerprint:
          type:
            - string
            - 'null'
        retained_check:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
          required:
            - id
          description: >-
            The compliance check that produced this alert. Null for older
            alerts.
      required:
        - origin
        - created_by
        - agreement_version
        - invoice_fingerprint
        - retained_check
      description: >-
        Who or what created the alert, and from which agreement version and
        check.
    AlertActor:
      type:
        - object
        - 'null'
      properties:
        user:
          type: object
          properties:
            id:
              type: string
            name:
              type:
                - string
                - 'null'
            deleted:
              type: boolean
              description: >-
                The account was deleted. The name is kept, or null once the
                account is anonymised.
          required:
            - id
            - name
            - deleted
        api_key:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
          required:
            - id
            - name
          description: The API key used, retained after revocation.
      required:
        - user
        - api_key
      description: A person, and the API key they used if any.
  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.