> ## 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 a social media URL

> Submits the URL of a public social media post for analysis, as an
alternative to uploading a file. Use the returned `requestId` with
`GET /api/media/users/{requestId}` to fetch the result.

Supported platforms: Facebook, Instagram, Twitter/X, YouTube, TikTok
and Threads.

The URL must point to a specific post, video, reel or photo (for
example `youtube.com/watch?v=…`, `youtu.be/…`, `/shorts/…`,
`x.com/<user>/status/<id>`, `instagram.com/p/…` or `/reel/…`,
`tiktok.com/@user/video/<id>`, `threads.net/@user/post/…`). The
`http(s)://` scheme is optional. Profile and home-page URLs are
rejected with 422.

While the media is being downloaded the scan status is `DOWNLOADING`;
if the download fails, the status becomes `DOWNLOAD_FAILED`.



## OpenAPI

````yaml /openapi/realscan.json post /api/files/social
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/files/social:
    post:
      tags:
        - RealScan
      summary: Submit a social media URL
      description: |-
        Submits the URL of a public social media post for analysis, as an
        alternative to uploading a file. Use the returned `requestId` with
        `GET /api/media/users/{requestId}` to fetch the result.

        Supported platforms: Facebook, Instagram, Twitter/X, YouTube, TikTok
        and Threads.

        The URL must point to a specific post, video, reel or photo (for
        example `youtube.com/watch?v=…`, `youtu.be/…`, `/shorts/…`,
        `x.com/<user>/status/<id>`, `instagram.com/p/…` or `/reel/…`,
        `tiktok.com/@user/video/<id>`, `threads.net/@user/post/…`). The
        `http(s)://` scheme is optional. Profile and home-page URLs are
        rejected with 422.

        While the media is being downloaded the scan status is `DOWNLOADING`;
        if the download fails, the status becomes `DOWNLOAD_FAILED`.
      operationId: socialUpload
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSocialRequest'
            example:
              socialLink: https://www.youtube.com/watch?v=6O0fySNw-Lw
      responses:
        '200':
          description: Social media URL accepted for analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSocialResponse'
              example:
                code: ok
                response: ''
                errno: 0
                requestId: 8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
        '400':
          description: >-
            Invalid or missing fields, or the organization has reached its
            upload limit (error code `upload-limit-reached`). A failed upload
            record is still created when the limit is reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Unauthorized, authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: >-
            Either the organization is on the free tier (error code
            `free-tier-restriction`, "Forbidden: Social link uploads require a
            paid plan"), or the caller has the viewer role ("Forbidden
            resource").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '422':
          description: >-
            Unsupported social media provider link. Error code:
            `not-allowed-provider` ("Invalid provider link").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableError'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseError'
components:
  schemas:
    PostSocialRequest:
      type: object
      properties:
        socialLink:
          type: string
          description: URL of the public social media post to analyze.
        tags:
          minItems: 1
          type: array
          description: Labels to attach to the scan.
          items:
            type: string
            minLength: 1
            maxLength: 128
      required:
        - socialLink
    PostSocialResponse:
      type: object
      properties:
        code:
          type: string
          description: '`ok` on success.'
        response:
          type: string
          description: Empty on success.
        errno:
          type: integer
          description: '`0` on success.'
        requestId:
          type: string
          description: ID used to fetch the result from `GET /api/media/users/{requestId}`.
      required:
        - code
        - response
        - errno
        - requestId
    BadRequestError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 400
    UnauthorizedError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 401
    ForbiddenError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 403
    UnprocessableError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 422
    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.

````