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

# Teach the agreement a rule from alerts (don't flag this again)

> Records a rule about alerts of this agreement, such as a tolerance you accept, and starts a run that suggests an edit to the agreement's instructions so later checks stop flagging such deviations. Nothing else changes: the alerts keep their verdict (unless to_review sets one for those still to review), claim and credit, and the instructions change only when someone accepts a suggestion (GET /v1/agreements/{id}/context-suggestions). The alerts show the rule's scope, whatever their verdict. To mark alerts as false alarms without stating a rule, use POST /v1/alerts/update. Every selected alert must belong to this agreement; a filter leaves other agreements' alerts out. Select alerts with alert_ids or filter, at most 5000 per request. Each call records a new rule and starts its own run, so check the agreement's runs before sending it again. The agreement's activity records who taught the rule, its note and what it decided (agreements.alert_rule_taught), and every verdict change it made names the rule (data.reason rule, data.rule_dismissal_id).



## OpenAPI

````yaml /openapi.json post /v1/agreements/{id}/teach
openapi: 3.1.0
info:
  title: Watchdog API
  version: 1.0.0
  description: >-
    The Watchdog API is served from https://api.watchdog.no. Request bodies are
    limited to 2 MiB unless an endpoint says otherwise. Files are uploaded
    directly to storage, not through the API.
servers:
  - url: https://api.watchdog.no
    description: Watchdog API
security: []
paths:
  /v1/agreements/{id}/teach:
    post:
      tags:
        - Agreements
      summary: Teach the agreement a rule from alerts (don't flag this again)
      description: >-
        Records a rule about alerts of this agreement, such as a tolerance you
        accept, and starts a run that suggests an edit to the agreement's
        instructions so later checks stop flagging such deviations. Nothing else
        changes: the alerts keep their verdict (unless to_review sets one for
        those still to review), claim and credit, and the instructions change
        only when someone accepts a suggestion (GET
        /v1/agreements/{id}/context-suggestions). The alerts show the rule's
        scope, whatever their verdict. To mark alerts as false alarms without
        stating a rule, use POST /v1/alerts/update. Every selected alert must
        belong to this agreement; a filter leaves other agreements' alerts out.
        Select alerts with alert_ids or filter, at most 5000 per request. Each
        call records a new rule and starts its own run, so check the agreement's
        runs before sending it again. The agreement's activity records who
        taught the rule, its note and what it decided
        (agreements.alert_rule_taught), and every verdict change it made names
        the rule (data.reason rule, data.rule_dismissal_id).
      operationId: teachAgreement
      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:
                alert_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  minItems: 1
                  maxItems: 5000
                  description: >-
                    Alerts to change. If any is unknown (404) or cannot be
                    changed (409), nothing changes.
                filter:
                  $ref: '#/components/schemas/AlertFilter'
                excluded_alert_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  minItems: 1
                  maxItems: 5000
                  description: >-
                    Alerts to leave out of a filter selection. Only valid with
                    filter.
                note:
                  type: string
                  minLength: 1
                  maxLength: 2000
                  description: >-
                    The rule, in your own words: what Watchdog should accept
                    from now on, ideally with a bound, such as "We accept
                    freight differences under 2 % of the line".
                to_review:
                  type: object
                  properties:
                    verdict:
                      type: string
                      enum:
                        - accepted
                        - dismissed
                        - skipped
                    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.
                      required:
                        - category
                      additionalProperties: false
                      description: >-
                        Why they are false alarms. Required with verdict
                        dismissed, and only valid with it. With category other,
                        the rule (note) explains them.
                  required:
                    - verdict
                  additionalProperties: false
                  description: >-
                    The verdict the selected alerts still to review take, in the
                    same transaction as the rule. Omit it to leave them to
                    review. False alarms made here start no run of their own;
                    the rule has one. Alerts in completed claims keep theirs.
              required:
                - note
              additionalProperties: false
      responses:
        '202':
          description: >-
            The rule is recorded and its suggestions are on the way. Follow the
            run with getWorkflowRun.
          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.
            Location:
              schema:
                type: string
              required: false
              description: Relative URL of the created or accepted resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeachAgreementResult'
        '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 agreement or an alert in alert_ids was not found.
          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 agreement or an alert in alert_ids was not found.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_not_found'
        '409':
          description: >-
            An alert in alert_ids belongs to another agreement, the filter
            matches no alert of this agreement, or it matches too many. Nothing
            changed.
          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: >-
                    An alert in alert_ids belongs to another agreement, the
                    filter matches no alert of this agreement, or it matches too
                    many. Nothing changed.
                  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:
    AlertFilter:
      type: object
      properties:
        view_ids:
          type: array
          items:
            type: string
        claim_ids:
          type: array
          items:
            type: string
        has_claim:
          type: boolean
          description: Attached to a claim now.
        claim_statuses:
          type: array
          items:
            type: string
            enum:
              - pending
              - in_progress
              - completed
              - cancelled
          description: Of the current claim.
        invoice_ids:
          type: array
          items:
            type: string
            format: uuid
        company_ids:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Alerts on invoices of these workspace companies: a company scope,
            applied to every alert whatever join_operator says.
        agreement_ids:
          type: array
          items:
            type: string
            format: uuid
        purchase_order_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Alerts of purchase-order checks against these orders.
        agreement_statuses:
          type: array
          items:
            type: string
            enum:
              - draft
              - active
              - archived
        supplier_ids:
          type: array
          items:
            type: string
            format: uuid
        recipient_ids:
          type: array
          items:
            type: string
            format: uuid
        tag_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Tags of the agreement.
        topic_ids:
          type: array
          items:
            type: string
        has_topic:
          type: boolean
        check_types:
          type: array
          items:
            type: string
            enum:
              - agreement
              - purchase_order
              - duplicate
        verdicts:
          type: array
          items:
            type: string
            enum:
              - pending
              - accepted
              - dismissed
              - skipped
          description: >-
            Whatever the credit. pending: to review; accepted: confirmed;
            dismissed: false alarm; skipped: unsure. Reviewed: all but pending.
        credited:
          type: boolean
          description: Whatever the verdict.
        confidence_levels:
          type: array
          items:
            type: string
            enum:
              - certain
              - uncertain
              - 'null'
        currency_codes:
          type: array
          items:
            type: string
            pattern: ^[A-Z]{3}$
        correction_types:
          type: array
          items:
            type: string
            enum:
              - modify_item
              - modify_invoice
              - add_item
        agreement_version_status:
          type: string
          enum:
            - current
            - older
          description: >-
            The alert assessed the current agreement version or an older one; an
            unknown version or no agreement matches neither.
        validity:
          type: string
          enum:
            - live
            - invalidated
            - all
          description: >-
            live (default): alerts that count; invalidated: those that stopped
            (invalidation.reason says why). Alerts in claims named by claim_ids
            are included either way.
        impact_min:
          type: string
          maxLength: 100
          pattern: ^-?\d+(?:\.\d+)?$
          description: >-
            Impact in the organization currency, inclusive. Alerts without one
            never match.
        impact_max:
          type: string
          maxLength: 100
          pattern: ^-?\d+(?:\.\d+)?$
        issued_from:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Invoice issue date.
        issued_through:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        created_from:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        created_through:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        search:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            Alert, invoice, supplier, agreement and topic text. A UUID matches
            the alert, invoice, supplier or agreement ID.
        join_operator:
          type: string
          enum:
            - and
            - or
          description: >-
            or combines only the invoice, agreement, supplier, recipient and
            topic IDs.
        not:
          type: array
          items:
            type: string
            enum:
              - claim_ids
              - claim_statuses
              - invoice_ids
              - agreement_ids
              - purchase_order_ids
              - agreement_statuses
              - supplier_ids
              - recipient_ids
              - tag_ids
              - topic_ids
              - check_types
              - verdicts
              - confidence_levels
              - currency_codes
              - correction_types
          description: List filters to invert.
      additionalProperties: false
    TeachAgreementResult:
      type: object
      properties:
        workflow_run_id:
          type: string
          format: uuid
          description: The agreement_context_suggestions run interpreting the rule.
        alert_count:
          type: integer
          exclusiveMinimum: 0
          description: Alerts the rule was taught from.
        changed_count:
          type: integer
          minimum: 0
          description: Alerts still to review that took the to_review verdict.
      required:
        - workflow_run_id
        - alert_count
        - changed_count
    Error_validation_error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_error
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_invalid_token:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_token
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - forbidden
                - token_disabled
                - organization_required
                - insufficient_role
                - mfa_required
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_not_found:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - not_found
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_conflict:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - conflict
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_rate_limit_exceeded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - rate_limit_exceeded
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_internal_error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - internal_error
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_service_unavailable:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - service_unavailable
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: >-
        Personal API key sent as a bearer token, together with
        X-Organization-Id. The key must have at least the access level the
        endpoint requires (read, write or admin).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.