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

# Import uploads from a link

> Imports media from a link (YouTube, a cloud drive, a direct file URL…): one upload per selection, downloaded in the background; answers 202 with the new uploads. Each selection names an assetId and a qualityId from discovery, which this REST API does not offer: ask GraphQL (POST https://api.streamloop.app/graphql, the same X-API-Key) with `query { externalLinkContents(url: "<link>") { provider items { id name durationSeconds qualities { id label height } } } }` — an item's id is the assetId, a quality's id the qualityId — or use the MCP tool discover_external_media. Then poll GET /uploads/{id}: externalSource.state.status goes PENDING, RESOLVING, DOWNLOADING, UPLOADING, then COMPLETED (uploaded true) or FAILED (state.error says why). The Location header is the first upload's; the body has every id.



## OpenAPI

````yaml https://api.streamloop.app/v1/openapi.json post /uploads/from-link
openapi: 3.1.0
info:
  contact:
    name: Streamloop
    url: https://streamloop.app
  description: >-
    The Streamloop REST API. Authenticate with either an `X-API-Key` header (a
    Streamloop API key, prefix `sl_` — simplest for programmatic clients) or an
    OAuth 2.1 bearer access token (obtain one via https://auth.streamloop.app).
    With an API key, name the workspace in `X-Workspace-Id` (GET /workspaces
    lists yours). Collections are cursor-paginated (`limit` + `cursor`,
    returning `{ data, page }`). Errors are RFC 7807 problem documents.
  summary: >-
    Programmatic access to Streamloop — create and control 24/7 loop streams,
    manage media, destinations, playlists, and billing.
  title: Streamloop API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.streamloop.app/v1
security:
  - oauth2: []
  - bearerAuth: []
  - apiKey: []
tags:
  - description: The authenticated user's account and workspaces.
    name: account
  - description: Credits, usage analytics, invoices, and top-ups.
    name: billing
  - description: Crypto deposit options for topping up credits.
    name: crypto
  - description: Manage streaming destinations (custom RTMP).
    name: destinations
  - description: Service metadata, discovery documents, and batch execution.
    name: meta
  - description: 'Stream and scene playlists: list, create, edit and publish.'
    name: playlists
  - description: >-
      Create, control, schedule, and monitor 24/7 streams: their destinations
      and scene.
    name: streams
  - description: Upload and manage source media (video/audio).
    name: uploads
paths:
  /uploads/from-link:
    post:
      tags:
        - uploads
      summary: Import uploads from a link
      description: >-
        Imports media from a link (YouTube, a cloud drive, a direct file URL…):
        one upload per selection, downloaded in the background; answers 202 with
        the new uploads. Each selection names an assetId and a qualityId from
        discovery, which this REST API does not offer: ask GraphQL (POST
        https://api.streamloop.app/graphql, the same X-API-Key) with `query {
        externalLinkContents(url: "<link>") { provider items { id name
        durationSeconds qualities { id label height } } } }` — an item's id is
        the assetId, a quality's id the qualityId — or use the MCP tool
        discover_external_media. Then poll GET /uploads/{id}:
        externalSource.state.status goes PENDING, RESOLVING, DOWNLOADING,
        UPLOADING, then COMPLETED (uploaded true) or FAILED (state.error says
        why). The Location header is the first upload's; the body has every id.
      operationId: createUploadFromLink
      parameters:
        - description: >-
            Workspace this request operates in — the workspace id (`wksp_…`) or
            the organization id, from GET /workspaces. Required with an API key,
            which carries no workspace (400 `WORKSPACE_REQUIRED` without it).
            With an OAuth token it defaults to the workspace the token was
            issued for. Responds 403 `WORKSPACE_FORBIDDEN` when the caller is
            not a current member, rather than falling back to another workspace.
          in: header
          name: X-Workspace-Id
          required: false
          schema:
            type: string
        - description: >-
            Optional client-generated key. A repeated request with the same key,
            method and path (by the same caller in the same workspace) replays
            the original response, with `Idempotency-Replayed: true`, for 24
            hours instead of running again — safe retries. The same key with a
            different body is refused with 422 IDEMPOTENCY_KEY_REUSED (nothing
            runs): use a new key for each new request. A 5xx answer is not
            remembered (a retry runs).
          in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadFromLinkRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Upload'
                type: array
          description: >-
            Accepted — the work goes on in the background; the body has its ids
            and Location is where to poll for the result.
          headers:
            Location:
              description: >-
                Where to poll for the result: GET /uploads/{id} (the first
                item's, when the answer is a list; the body has every id).
              schema:
                type: string
            RateLimit:
              description: >-
                The same three as one structured field: limit=, remaining=,
                reset= (IETF RateLimit header fields draft).
              schema:
                type: string
            RateLimit-Limit:
              description: Requests allowed per window.
              schema:
                type: integer
            RateLimit-Policy:
              description: 'The quota and its window in seconds: 600;w=60.'
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: 'No workspace selected: send X-Workspace-Id (WORKSPACE_REQUIRED).'
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Missing or invalid access token.
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The token lacks the required scope or access to the resource.
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The resource does not exist or is not visible to the caller.
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            Conflicts with the resource's current state, e.g. STREAM_LIVE or
            IN_USE.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            The request is invalid, or refused for the resource as it is (the
            code says why).
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Rate limit exceeded. Retry after the indicated delay.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Unexpected failure (UPSTREAM_ERROR).
      security:
        - oauth2:
            - streamloop:write
        - bearerAuth: []
        - apiKey: []
components:
  schemas:
    CreateUploadFromLinkRequest:
      properties:
        selections:
          items:
            description: >-
              One asset and quality pair confirmed from ExternalLinkContents,
              optionally narrowed to a

              time range of the source.


              The same asset may appear several times with different ranges:
              each selection produces its

              own upload, so importing two clips of one video (or re-importing a
              different range of a

              video already imported) is a matter of repeating the asset with a
              new range.
            properties:
              assetId:
                type: string
              endSeconds:
                description: >-
                  Import only up to this offset in the source, in seconds. Null
                  (the default) runs to the

                  end. Ranges past the end of the source are truncated by the
                  provider.
                type:
                  - number
                  - 'null'
              preciseCut:
                description: >-
                  Cut exactly at the requested offsets instead of snapping to
                  the nearest keyframes. This

                  re-encodes around each cut, so the import is markedly slower;
                  the default (false) is a

                  stream copy whose start may include up to a few seconds of
                  preceding video. Ignored when

                  no range is given.
                type:
                  - boolean
                  - 'null'
              qualityId:
                type: string
              startSeconds:
                description: >-
                  Import only from this offset in the source, in seconds. Null
                  (the default) starts at the

                  beginning. Must be < endSeconds and < the item's
                  durationSeconds when it is known.
                type:
                  - number
                  - 'null'
            required:
              - assetId
              - qualityId
            type: object
          type: array
        url:
          type: string
      required:
        - selections
        - url
      type: object
    Upload:
      properties:
        createdAt:
          format: date-time
          type: string
        downloadUrl:
          type:
            - string
            - 'null'
        duration:
          type:
            - integer
            - 'null'
        externalSource:
          properties:
            id:
              type: string
            provider:
              type:
                - string
                - 'null'
            state:
              properties:
                downloaded:
                  type: string
                error:
                  type:
                    - string
                    - 'null'
                eta:
                  type: integer
                progress:
                  type: number
                speed:
                  type: number
                status:
                  enum:
                    - PENDING
                    - RESOLVING
                    - DOWNLOADING
                    - UPLOADING
                    - COMPLETED
                    - FAILED
                  type: string
                total:
                  type: string
              required:
                - progress
                - status
              type:
                - object
                - 'null'
            type:
              type: string
            url:
              type: string
          required:
            - id
            - type
            - url
          type:
            - object
            - 'null'
        fileSize:
          type:
            - integer
            - 'null'
        fps:
          type:
            - number
            - 'null'
        hasAudio:
          type:
            - boolean
            - 'null'
        hasVideo:
          type:
            - boolean
            - 'null'
        height:
          type:
            - integer
            - 'null'
        id:
          type: string
        isDeleted:
          type:
            - boolean
            - 'null'
        meta:
          properties:
            audioStream:
              type:
                - string
                - 'null'
            videoStream:
              type:
                - string
                - 'null'
          type:
            - object
            - 'null'
        mimeType:
          type: string
        name:
          type: string
        orientation:
          type:
            - integer
            - 'null'
        path:
          type:
            - string
            - 'null'
        storage:
          type: string
        thumbnailUrl:
          type:
            - string
            - 'null'
        type:
          enum:
            - audio
            - video
            - image
          type: string
        updatedAt:
          format: date-time
          type: string
        uploaded:
          type: boolean
        width:
          type:
            - integer
            - 'null'
      required:
        - id
        - name
        - uploaded
      type: object
    Problem:
      additionalProperties:
        description: Details of the refusal beyond its code, e.g. reason.
      description: RFC 7807 problem-details error body.
      properties:
        code:
          description: >-
            A stable, machine-readable error code: branch on it, not on the HTTP
            status. 400: BAD_REQUEST, INVALID_BATCH, WORKSPACE_REQUIRED. 401:
            UNAUTHENTICATED. 402: INSUFFICIENT_CREDITS. 403: FORBIDDEN,
            INSUFFICIENT_SCOPE, MULTISTREAM_NOT_ENABLED. 404: NOT_FOUND. 405:
            METHOD_NOT_ALLOWED. 409: CONFLICT, DESTINATION_DUPLICATE,
            DESTINATION_LIMIT, IMMUTABLE_WHILE_LIVE, IN_USE, LAST_DESTINATION,
            MIRROR_DESTINATION_CHANGE_BLOCKED, NOT_LIVE, STALE_DRAFT,
            STREAM_ILLEGAL_TRANSITION, STREAM_LIVE, UPLOAD_ALREADY_COMPLETED,
            UPLOAD_INCOMPLETE, YOUTUBE_DESTINATION_LIMIT. 410: GONE. 422:
            DESTINATION_INCOMPATIBLE, FILE_TOO_LARGE, IDEMPOTENCY_KEY_REUSED,
            INVALID_INPUT, SCENE_ASSET_MISSING, SCENE_MISSING,
            SCENE_NOT_PUBLISHED, SCENE_PLAYLISTS_UNSUPPORTED,
            SCENE_PLAYLIST_MISSING, SCENE_QUALITY_UNSUPPORTED,
            STREAM_GUARD_FAILED, UNSUPPORTED_TYPE, UPLOAD_REMOVED. 429:
            RATE_LIMITED. 500: INTERNAL. 502: UPSTREAM_ERROR. 503:
            EXTERNAL_UPLOAD_ENQUEUE_FAILED, UNAVAILABLE. Other codes: 404 for
            *_NOT_FOUND, 403 for *_FORBIDDEN, 503 for *_UNAVAILABLE, else 422.
            502 UPSTREAM_ERROR is an unexpected failure.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence.
          type: string
        status:
          description: The HTTP status code.
          type: integer
        title:
          description: A short, human-readable summary of the problem.
          type: string
        type:
          description: A URI reference identifying the problem type.
          format: uri-reference
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
      type: object
  securitySchemes:
    oauth2:
      description: OAuth 2.1 authorization-code flow with PKCE.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.streamloop.app/api/auth/oauth2/authorize
          scopes:
            streamloop:billing: Read billing/usage and create top-up links
            streamloop:destructive: Delete streams and destinations
            streamloop:read: Read streams, destinations, playlists, and billing status
            streamloop:write: Create and control streams, destinations, and playlists
          tokenUrl: https://auth.streamloop.app/api/auth/oauth2/token
      type: oauth2
    bearerAuth:
      bearerFormat: JWT
      description: An OAuth 2.1 bearer access token.
      scheme: bearer
      type: http
    apiKey:
      description: >-
        A Streamloop API key (prefix `sl_`), sent in the `X-API-Key` header.
        Create and manage keys in the dashboard. The simplest auth for
        programmatic / agent clients — no OAuth flow required; the key acts as
        its owning user.
      in: header
      name: X-API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.