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

# Upload from URL (async)

<Warning>
  This endpoint uses a different base URL:

  `https://media.postflow.app/api/v1`
</Warning>


## OpenAPI

````yaml media.json POST /upload/url
openapi: 3.1.0
info:
  title: PostFlow Media Server
  version: '1'
  description: >-
    Media Server API for uploading and processing media files.


    The Media Server handles file uploads, processing, and storage. It supports
    synchronous and asynchronous uploads via file or URL.
servers:
  - url: https://media.postflow.app/api/v1
security:
  - http: []
paths:
  /upload/url:
    post:
      summary: Upload from URL (async)
      description: >-
        Asynchronous URL upload. The file is downloaded and processed in the
        background.


        Use the returned `status_url` to poll for completion. Alternatively, you
        can provide a `callback_url`, and PostFlow will notify you.
      operationId: upload.urlAsync
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file_url:
                  type: string
                  format: uri
                  description: URL of the file to download and upload.
                callback_url:
                  type:
                    - string
                    - 'null'
                  format: uri
                  description: >-
                    Optional webhook URL. When processing is done, `POST`
                    request is sent to this URL with a JSON body:


                    - `media_id` — string

                    - `status` — `completed` or `failed`

                    - `error` — string, only present when status is `failed`
              required:
                - file_url
      responses:
        '202':
          description: Upload accepted and queued for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  media_id:
                    type: string
                    description: The ID of the media being processed.
                  status_url:
                    type: string
                    format: uri
                    description: URL to poll for upload status.
                required:
                  - media_id
                  - status_url
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Initialization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message.
      required:
        - error
  securitySchemes:
    http:
      type: http
      scheme: bearer

````