> ## Documentation Index
> Fetch the complete documentation index at: https://docs.watchdoc.sphinxhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send feedback on a check

> Tell us the engine got this check right or wrong. Supply `flag_code` to name a specific detector, omit it to talk about the overall verdict.



## OpenAPI

````yaml /api_schema.yaml post /api/v1/document-checks/{id}/feedback/
openapi: 3.0.3
info:
  title: Sphinx Document Fraud API
  version: 1.0.0
  description: >
    Detect forged, tampered, and AI-generated documents. Upload a PDF or image
    and get back a

    structured verdict with a defined set of fraud flags.


    **Quick Start:**

    1. **Create an API key**: sign up, then generate a key from Settings.

    2. **Submit a document**: `POST /api/v1/document-checks/` with a file or a
    URL.
       You get back an id with status `"processing"`.
    3. **Poll for the result**: `GET /api/v1/document-checks/{id}/` until status
    is
       `"completed"` or `"failed"`.

    Optionally pass `webhook_url` on submit to be notified when analysis
    finishes, or

    `?wait=true` to block the submit request for up to 55s.


    **Authentication:** `Authorization: Bearer <api_key>`


    **Decisions:** Every completed check returns a decision (`clear`, `pending`,
    `suspicious`, or

    `fraudulent`), a `risk_level`, a plain-language summary, structured flags,
    and any

    workspace rules that triggered. The four-value decision set is the v1
    contract.
servers:
  - url: /
    description: This environment
security: []
tags:
  - name: Document Checks
    description: |-
      Submit a document for fraud analysis and retrieve structured results.

      **Allowed file types:** PDF, PNG, JPG.
  - name: Rules
    description: >-
      Workspace rules that guide the fraud engine, plus the score cut lines that
      set the `action` field on each check.
paths:
  /api/v1/document-checks/{id}/feedback/:
    post:
      tags:
        - Document Checks
      summary: Send feedback on a check
      description: >-
        Tell us the engine got this check right or wrong. Supply `flag_code` to
        name a specific detector, omit it to talk about the overall verdict.
      operationId: v1_document_checks_feedback_create
      parameters:
        - in: path
          name: id
          schema:
            type: string
          description: The document check id, e.g. `dc_9f2c4b1e8a7d4c3fb2e1d0a9c8b7a6f5`.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckFeedbackCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CheckFeedbackCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CheckFeedbackCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckFeedback'
          description: The recorded feedback.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid input. See `error.message`.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: The key's workspace role lacks the required permission.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: No such check in this workspace.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CheckFeedbackCreate:
      type: object
      description: >-
        `flag_code` present → flag feedback; omitted → verdict. `kind` is
        derived.
      properties:
        rating:
          $ref: '#/components/schemas/RatingEnum'
        flag_code:
          type: string
          default: ''
        corrected_decision:
          default: ''
          oneOf:
            - $ref: '#/components/schemas/DecisionEnum'
            - $ref: '#/components/schemas/BlankEnum'
        reason:
          type: string
          default: ''
          maxLength: 5000
      required:
        - rating
    CheckFeedback:
      type: object
      properties:
        id:
          type: integer
        object:
          type: string
          default: check_feedback
        created_at:
          type: string
        document_check:
          type: string
        kind:
          allOf:
            - $ref: '#/components/schemas/FeedbackKindEnum'
          description: |-
            Derived from whether `flag_code` was sent.

            * `verdict` - verdict
            * `flag` - flag
        rating:
          $ref: '#/components/schemas/RatingEnum'
        flag_code:
          type: string
          nullable: true
        corrected_decision:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/DecisionEnum'
            - $ref: '#/components/schemas/NullEnum'
        reason:
          type: string
          nullable: true
      required:
        - corrected_decision
        - created_at
        - document_check
        - flag_code
        - id
        - kind
        - rating
        - reason
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - error
    RatingEnum:
      enum:
        - agree
        - disagree
      type: string
      description: |-
        * `agree` - agree
        * `disagree` - disagree
    DecisionEnum:
      enum:
        - clear
        - pending
        - suspicious
        - fraudulent
      type: string
      description: |-
        * `clear` - clear
        * `pending` - pending
        * `suspicious` - suspicious
        * `fraudulent` - fraudulent
    BlankEnum:
      enum:
        - ''
    FeedbackKindEnum:
      enum:
        - verdict
        - flag
      type: string
      description: |-
        * `verdict` - verdict
        * `flag` - flag
    NullEnum:
      enum:
        - null
    ErrorDetail:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ErrorTypeEnum'
        code:
          type: string
          description: Machine-readable cause, e.g. `unsupported_document`.
        message:
          type: string
          description: Human-readable explanation. Safe to log; do not parse.
      required:
        - code
        - message
        - type
    ErrorTypeEnum:
      enum:
        - invalid_request_error
        - authentication_error
        - insufficient_credits_error
        - permission_error
        - not_found_error
        - rate_limit_error
        - api_error
      type: string
      description: |-
        * `invalid_request_error` - invalid_request_error
        * `authentication_error` - authentication_error
        * `insufficient_credits_error` - insufficient_credits_error
        * `permission_error` - permission_error
        * `not_found_error` - not_found_error
        * `rate_limit_error` - rate_limit_error
        * `api_error` - api_error
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Paste your workspace API key from Settings. Sent as Authorization:
        Bearer <key>.

````