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

# Submit feedback on a result

> Records the caller's label and feedback category for a completed scan
result, attributed to the caller and their organization.

Feedback may be submitted by the user who uploaded the media or by any
member of the same organization. The caller also needs a RealScan
role (owner, admin, contributor or viewer). Other callers get `403` "Forbidden resource".

### Errors

- `400` — no media result exists for the given `requestId`
  (`"Media result does not exist!"`).
- `401` — authentication failed.
- `403` — the caller may not submit feedback for that result
  (`"You are not authorized to create feedback for this media result!"`),
  or the caller's role is not allowed (`"Forbidden resource"`).



## OpenAPI

````yaml /openapi/realscan.json post /api/v2/user-feedback
openapi: 3.1.1
info:
  title: Reality Defender RealScan API
  description: |-
    > **Note:** Reality Defender recommends the
    > [Reality Defender SDKs](/sdks/quickstart) (Python, TypeScript, Go, Java
    > and Rust) for most integrations.

    ## Authentication

    Every request except `PUT /api/files/{requestId}` (authorized by its
    `token`) and `GET /api/health` must send your API key in the `X-API-KEY`
    header (header names are case-insensitive). Create a key on the Reality
    Defender web platform under
    [API keys](https://app.realitydefender.ai/api-keys).

    API keys are linked to a user. Organization owners, admins and viewers
    can view uploads from all users in the organization; contributors see
    only their own.

    ## Workflow

    1. Request a signed upload URL with `POST /api/files/aws-presigned`.
    2. `PUT` the file to the returned `signedUrl`. Alternatively, skip both
       steps and submit a social media URL with `POST /api/files/social`.
    3. Poll `GET /api/media/users/{requestId}` until the scan reaches a final
       status, or set up a webhook. Analysis time varies with file size and
       type.

    ## Interpreting results

    Focus on the ensemble result (`overallStatus` and `resultsSummary`) rather
    than on individual model results.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.prd.realitydefender.xyz
security:
  - apiKey: []
tags:
  - name: RealScan
    description: >-
      Deepfake detection for uploaded files and social media links: upload, scan
      status and results, usage, and feedback.
paths:
  /api/v2/user-feedback:
    post:
      tags:
        - RealScan
      summary: Submit feedback on a result
      description: >-
        Records the caller's label and feedback category for a completed scan

        result, attributed to the caller and their organization.


        Feedback may be submitted by the user who uploaded the media or by any

        member of the same organization. The caller also needs a RealScan

        role (owner, admin, contributor or viewer). Other callers get `403`
        "Forbidden resource".


        ### Errors


        - `400` — no media result exists for the given `requestId`
          (`"Media result does not exist!"`).
        - `401` — authentication failed.

        - `403` — the caller may not submit feedback for that result
          (`"You are not authorized to create feedback for this media result!"`),
          or the caller's role is not allowed (`"Forbidden resource"`).
      operationId: createUserFeedback
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserFeedbackRequest'
            example:
              requestId: 8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
              label: REAL
              feedbackCategory: CONFIRMATION
              comment: Looks correct in context.
      responses:
        '201':
          description: User feedback created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFeedback'
              example:
                id: 5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f
                userId: user_0123456789abcdef
                requestId: 8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
                institutionId: 3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b
                text: Looks correct in context.
                category: CONFIRMATION
                userName: Jane Doe
                userEmail: jane@example.com
                orgName: Organization name
                mediaType: VIDEO
                mediaViewUrl: >-
                  https://app.realitydefender.ai/media/8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
                mediaSource: api:My integration key
                label: REAL
                createdAt: '2025-01-15T12:00:00.000Z'
                updatedAt: '2025-01-15T12:00:00.000Z'
        '400':
          description: >-
            Media result does not exist ("Media result does not exist!"), or
            invalid fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: >-
            Not authorized to create feedback for this media result ("You are
            not authorized to create feedback for this media result!"), or the
            caller's role is not allowed ("Forbidden resource").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseError'
components:
  schemas:
    CreateUserFeedbackRequest:
      type: object
      properties:
        requestId:
          type: string
          minLength: 1
          description: >-
            Request ID of the scan result, from the presigned, social or media
            detail response, or from the web app when viewing the result.
        label:
          type: string
          description: Your label for the content.
          enum:
            - REAL
            - SYNTHETIC
            - MANIPULATED
            - UNKNOWN
        feedbackCategory:
          type: string
          description: Type of feedback.
          enum:
            - FALSE_POSITIVE
            - FALSE_NEGATIVE
            - CONFIRMATION
            - OTHER
        comment:
          type: string
          description: >-
            Optional free-text comment, stored as `text`. If omitted, no comment
            is stored.
      required:
        - requestId
        - label
        - feedbackCategory
    UserFeedback:
      type: object
      description: >-
        Created feedback record. Field presence may vary with the user profile
        and the stored result.
      properties:
        id:
          type: string
          format: uuid
        category:
          type: string
          description: The submitted `feedbackCategory`.
          enum:
            - FALSE_POSITIVE
            - FALSE_NEGATIVE
            - CONFIRMATION
            - OTHER
        institutionId:
          type: string
        userId:
          type: string
        requestId:
          type: string
        text:
          type: string
          nullable: true
          description: The submitted `comment`; only set when a comment was sent.
        label:
          type: string
          nullable: true
        userName:
          type: string
          nullable: true
        userEmail:
          type: string
          nullable: true
        orgName:
          type: string
          nullable: true
        mediaType:
          type: string
          nullable: true
        mediaViewUrl:
          type: string
          nullable: true
        mediaSource:
          type: string
          nullable: true
          description: >-
            `api` or `api:<key name>` for API submissions; otherwise a value
            naming how the media was submitted, for example `social_link` or
            `file_upload`.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - category
        - institutionId
        - userId
        - requestId
        - createdAt
        - updatedAt
    BadRequestError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 400
    ForbiddenError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 403
    BaseError:
      type: object
      properties:
        statusCode:
          type: integer
        path:
          type: string
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        code:
          oneOf:
            - type: string
              nullable: true
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
        type:
          type: string
          description: >-
            Present only for import errors (for example
            `unsupported-file-format`).
        name:
          type: string
          description: >-
            Present only for import errors (for example
            `unsupported-file-format`).
        explanation:
          type: string
          description: >-
            Present only for import errors (for example
            `unsupported-file-format`).
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        API key created in the web app under API keys. Expired or disabled keys
        are rejected with 401.

````