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

# List media (first page)

> Legacy unpaged form of the media list. Returns page 0 of the caller's
own media; `size` defaults to 15. New integrations should use
`GET /api/v2/media/users/pages/{page}`, which supports reading further
pages.

Supports the size, date, name, mediaType, tags, sort and manipulation
filters; tags match only the caller's own tags. `userIds`, `origin`,
`webUploaded` and `socialLink` are ignored.



## OpenAPI

````yaml /openapi/realscan.json get /api/v2/media/users
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/media/users:
    get:
      tags:
        - RealScan
      summary: List media (first page)
      description: |-
        Legacy unpaged form of the media list. Returns page 0 of the caller's
        own media; `size` defaults to 15. New integrations should use
        `GET /api/v2/media/users/pages/{page}`, which supports reading further
        pages.

        Supports the size, date, name, mediaType, tags, sort and manipulation
        filters; tags match only the caller's own tags. `userIds`, `origin`,
        `webUploaded` and `socialLink` are ignored.
      operationId: getMediaListV2
      parameters:
        - $ref: '#/components/parameters/MediaList_size'
        - $ref: '#/components/parameters/MediaList_startDate'
        - $ref: '#/components/parameters/MediaList_endDate'
        - $ref: '#/components/parameters/MediaList_name'
        - $ref: '#/components/parameters/MediaList_mediaType'
        - $ref: '#/components/parameters/MediaList_tags'
        - $ref: '#/components/parameters/MediaList_sortBy'
        - $ref: '#/components/parameters/MediaList_sortDirection'
        - $ref: '#/components/parameters/MediaList_manipulation'
      responses:
        '200':
          description: First page of the caller's media (size defaults to 15)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMediaListV2Response'
              example:
                totalItems: 1
                totalPages: 1
                currentPage: 0
                currentPageItemsCount: 1
                mediaList:
                  - requestId: 8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
                    filename: your_file_1736942400000.mp4
                    originalFileName: your-file.mp4
                    mediaType: VIDEO
                    overallStatus: AUTHENTIC
                    uploadedDate: '2025-01-15T12:00:00.000Z'
                    resultsSummary:
                      status: AUTHENTIC
                      metadata:
                        finalScore: 12
        '400':
          description: Invalid or missing fields, values, or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseError'
components:
  parameters:
    MediaList_size:
      name: size
      required: false
      in: query
      description: Page size; must be ≥ 1. The default depends on the endpoint.
      schema:
        maximum: 1000
        type: integer
        format: int64
    MediaList_startDate:
      name: startDate
      required: false
      in: query
      description: >-
        Return items uploaded on or after this date (`YYYY-MM-DD`). Invalid
        dates are ignored.
      schema:
        type: string
    MediaList_endDate:
      name: endDate
      required: false
      in: query
      description: >-
        Return items created at or before this instant. A bare `YYYY-MM-DD`
        means 00:00 UTC, so it excludes that day; pass the next day or a full
        timestamp. Invalid dates are ignored.
      schema:
        type: string
    MediaList_name:
      name: name
      required: false
      in: query
      description: Case-insensitive substring match on the scan name or original file name.
      schema:
        type: string
    MediaList_mediaType:
      name: mediaType
      required: false
      in: query
      description: Return only items of these media types.
      schema:
        type: array
        items:
          type: string
          enum:
            - audio
            - video
            - image
            - text
    MediaList_tags:
      name: tags
      required: false
      in: query
      description: Return only items carrying these tags.
      schema:
        type: array
        items:
          type: string
    MediaList_sortBy:
      name: sortBy
      required: false
      in: query
      description: Field to sort by. `name` sorts by scan name. Default `createdAt`.
      schema:
        type: string
        enum:
          - name
          - createdAt
    MediaList_sortDirection:
      name: sortDirection
      required: false
      in: query
      description: Sort direction. Default `DESC`.
      schema:
        type: string
        enum:
          - ASC
          - DESC
    MediaList_manipulation:
      name: manipulation
      required: false
      in: query
      description: >-
        AUTHENTIC/SUSPICIOUS/MANIPULATED filter on overall score
        1–44/45–55/56–100. NONE returns NOT_APPLICABLE, UNABLE_TO_EVALUATE and
        DOWNLOAD_FAILED.
      schema:
        type: array
        items:
          type: string
          enum:
            - AUTHENTIC
            - SUSPICIOUS
            - MANIPULATED
            - NONE
  schemas:
    GetMediaListV2Response:
      type: object
      properties:
        totalItems:
          type: number
          description: Total number of items matching the filters.
        mediaList:
          type: array
          description: Items of this page, each shaped like the media detail response.
          items:
            $ref: '#/components/schemas/MediaItem'
        totalPages:
          type: number
          description: Total number of pages.
        currentPage:
          type: number
          description: Zero-based number of this page.
        currentPageItemsCount:
          type: number
          description: Number of items in this page.
      required:
        - totalItems
        - mediaList
        - totalPages
        - currentPage
        - currentPageItemsCount
    BadRequestError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 400
    InternalServerError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 500
    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`).
    MediaItem:
      type: object
      properties:
        requestId:
          type: string
          description: ID used to fetch this result.
        name:
          type: string
          description: >-
            Storage key of the uploaded media object. Use `scanName` for
            display.
        scanName:
          type: string
          description: Name given to the scan.
        filename:
          type: string
          description: Display / upload file name.
        originalFileName:
          type: string
          description: Original uploaded file name.
        mediaType:
          type: string
          description: '`IMAGE`, `VIDEO`, `AUDIO` or `TEXT`.'
        overallStatus:
          $ref: '#/components/schemas/ScanStatus'
        origin:
          type: string
          description: API key name (or redacted key), `Social link`, or `Uploaded`.
        socialLink:
          type: string
          description: >-
            Social media URL. Always present; meaningful only for social media
            submissions.
        socialLinkDownloaded:
          type: boolean
          description: >-
            Whether the social media URL was downloaded. Always present;
            meaningful only for social media submissions.
        socialLinkDownloadFailed:
          type: boolean
          description: >-
            Whether downloading the social media URL failed. Always present;
            meaningful only for social media submissions.
        showAudioResult:
          type: boolean
          description: >-
            For video scans, whether the extracted-audio result is included in
            this result. Set at upload from the request or the organization's
            auto audio analysis setting, or later when audio analysis is
            requested. Usually `false` for non-video media.
        audioRequestId:
          type: string
          nullable: true
          description: >-
            Request ID of the extracted-audio scan, set for every video scan;
            `''` or null otherwise.
        thumbnail:
          type: string
          description: Pre-signed thumbnail URL, or `""` when unavailable.
        userId:
          type: string
          description: ID of the uploading user.
        institutionId:
          type: string
          nullable: true
          description: Organization ID.
        releaseVersion:
          type: string
          description: Platform release version used for the scan; defaults to `1.0.0`.
        uploadedDate:
          type: string
          description: Upload timestamp (ISO 8601).
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp.
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp.
        resultsSummary:
          type: object
          nullable: true
          description: Ensemble status, score, and optional reasons or error.
          properties:
            status:
              $ref: '#/components/schemas/ScanStatus'
            metadata:
              type: object
              properties:
                finalScore:
                  type: number
                  nullable: true
                  description: >-
                    Overall score, when present; always > 0 and < 100. Authentic
                    1–44, Suspicious 45–55, Manipulated 56–99. When the context
                    model sets the conclusion, `finalScore` may be null; use
                    `overallStatus`.
                languages:
                  type: array
                  description: Detected languages, for audio.
                  items:
                    type: string
                reasons:
                  type: array
                  description: Why the result is `NOT_APPLICABLE`.
                  items:
                    $ref: '#/components/schemas/ScanReason'
            error:
              type: object
              description: >-
                Why the scan failed, when the status is `UNABLE_TO_EVALUATE` or
                `DOWNLOAD_FAILED`.
              properties:
                code:
                  type: string
                  description: Stable machine-readable code, for example `model-error`.
                type:
                  type: string
                  description: >-
                    Category of the error: `Import error`, `Not applicable`,
                    `Processing error`, `System error` or `Download failed`.
                name:
                  type: string
                  description: Short human-readable title.
                explanation:
                  type: string
                  description: User-facing explanation.
          required:
            - status
            - metadata
        models:
          type: array
          description: >-
            Per-model detection results. Missing or in-flight models may appear
            with `status: ANALYZING` and null scores. Models that do not apply
            to the media type typically return `status: NOT_APPLICABLE` with
            `code: not_applicable` and `data: null`.
          items:
            type: object
            properties:
              name:
                type: string
                description: >-
                  Model slug. Model names can change as detectors are added,
                  renamed or retired.
              status:
                type: string
                description: >-
                  Model status, for example `FAKE`, `AUTHENTIC`, `SUSPICIOUS`,
                  `NOT_APPLICABLE`, `UNABLE_TO_EVALUATE` or `ANALYZING`.
              predictionNumber:
                type: number
                nullable: true
                description: >-
                  Raw model score when available, typically 0–1. Not restricted;
                  can be exactly `0` or `1`. `-1` when the model did not
                  evaluate the media.
              normalizedPredictionNumber:
                type: number
                nullable: true
                description: >-
                  Integer 1–99 when evaluated; negative (e.g. `-1`) when the
                  model did not evaluate the media.
              rollingAvgNumber:
                type: number
                nullable: true
                description: >-
                  Rolling average when applicable, with the same normalization
                  as `normalizedPredictionNumber`.
              finalScore:
                type: number
                nullable: true
                description: >-
                  Integer 1–99 when evaluated; negative (e.g. `-1`) when the
                  model did not evaluate the media. Authentic 1–44, Suspicious
                  45–55, Manipulated 56–99 (status `FAKE`).
              data:
                type: object
                nullable: true
                description: >-
                  Model-specific payload, for example `decision`, `score` and
                  `raw_score`. The shape varies by model.
              error:
                description: >-
                  Error details when the model failed. An object, a string or
                  null.
              code:
                type: string
                nullable: true
                description: >-
                  Machine-readable code, for example `not_applicable`; `error`
                  when the model failed.
        rdModels:
          type: array
          items:
            type: object
        storageLocation:
          type: string
          description: >-
            Pre-signed URL of the original uploaded media. May be empty if the
            original was deleted by the retention policy.
        aggregationResultUrl:
          type: string
          description: >-
            Storage key of the scan's `aggregation.json`. Not a downloadable
            URL; use `modelMetadataUrl` instead.
        modelMetadataUrl:
          type: string
          description: >-
            Pre-signed URL of the `aggregation.json` referenced by
            `aggregationResultUrl`. Fetch it to build UI-like visualizations.
        audioModelMetadataUrl:
          type: string
          description: >-
            Pre-signed URL of the extracted-audio aggregation JSON for video
            scans once the audio scan has finished; otherwise `""`.
        explainabilityUrl:
          type: string
          description: >-
            Pre-signed URL of the HTML explainability output, for text scans.
            Always `""` for image, video and audio.
        heatmaps:
          type: object
          description: >-
            Map of model name to pre-signed heatmap PNG URL, one entry per
            `models[]` item.
          additionalProperties:
            type: string
        tags:
          type: array
          description: Labels attached to the scan.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
    ScanStatus:
      type: string
      description: |-
        Status of a scan:

        - `ANALYZING` — analysis is in progress.
        - `NOT_APPLICABLE` — the media has characteristics known to affect
          accuracy; see `resultsSummary.metadata.reasons`.
        - `UNABLE_TO_EVALUATE` — processing failed, for example a model
          timeout or failure; see `resultsSummary.error`.
        - `DOWNLOADING` — a social media URL is still being downloaded.
        - `DOWNLOAD_FAILED` — the social media URL could not be downloaded;
          see `resultsSummary.error`.
        - `AUTHENTIC` — conclusion Authentic (score typically 1–44).
        - `FAKE` — conclusion Manipulated (score typically 56–99).
        - `SUSPICIOUS` — conclusion Suspicious (score typically 45–55).
      enum:
        - ANALYZING
        - NOT_APPLICABLE
        - UNABLE_TO_EVALUATE
        - DOWNLOADING
        - DOWNLOAD_FAILED
        - AUTHENTIC
        - FAKE
        - SUSPICIOUS
    ScanReason:
      type: object
      description: Why a result is `NOT_APPLICABLE`.
      properties:
        code:
          type: string
          description: >-
            Stable machine-readable code, for example `relevance: no faces
            detected/faces too small`.
        type:
          type: string
          description: >-
            Category of the reason:


            - `Import error` — the media could not be imported.

            - `Not applicable` — the media has characteristics known to affect
            accuracy.

            - `Processing error` — the models failed to process the media.

            - `System error` — a technical failure outside the models.

            - `Download failed` — the social media URL could not be downloaded.
          enum:
            - Import error
            - Not applicable
            - Processing error
            - System error
            - Download failed
        name:
          type: string
          description: Short human-readable title.
        explanation:
          type: string
          description: User-facing explanation.
        rawReason:
          type: string
          description: The detector's original reason string.
      required:
        - code
        - type
        - name
        - explanation
        - rawReason
  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.

````