Audio Delivery Network Upload Sessions API

openapi: 3.2.0
info:
  title: AudioDN Upload Sessions API
  version: 1.0.0
  summary: 'Audio delivery infrastructure: upload, transcode, secure delivery, and playback.'
  description: 'AudioDN provides a REST API and embeddable web components for managing and delivering audio at scale.


    Authentication: bearer token via the `Authorization` header. Use a server-side API key for full access; mint scoped client-side keys (Player or Uploader) for browsers and mobile apps.


    All endpoints are prefixed with `/v1/`.'
  contact:
    name: Audio Delivery Network
    email: support@audiodeliverynetwork.com
    url: https://audiodeliverynetwork.com
  license:
    name: Proprietary
servers:
- url: https://api.audiodelivery.net
  description: Production
security:
- BearerAuth: []
tags:
- name: Upload Sessions
paths:
  /v1/upload_session:
    post:
      tags:
      - Upload Sessions
      operationId: createUploadSession
      summary: Create upload session
      description: Creates an upload session for batch uploading tracks. By default returns an upload_session_id only — create tracks via POST /v1/upload/{upload_session_id}/track. Optionally include a nested `track` object to also create that track and receive track_id, the full track object (including delivery base_path/base_url), track_upload, and track_cover_upload on the session response (you can still add more tracks later).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - collection_id
              properties:
                collection_id:
                  type: string
                  format: uuid
                  description: Required unless the API key is scoped to a collection.
                creator_id:
                  type: string
                  format: uuid
                organization_index:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
                expires_in:
                  type: integer
                  description: Session duration in seconds (default 3600, min 60, max 86400).
                  minimum: 60
                  maximum: 86400
                  default: 3600
                track:
                  type: object
                  description: When present, also create that track and append track upload fields to the response.
                  required:
                  - file_name
                  properties:
                    file_name:
                      type: string
                      description: Original filename of the track. Required when track is present.
                    organization_index:
                      type: string
                    metadata:
                      type: object
                      additionalProperties: true
                    player_title:
                      type: string
                    player_subtitle:
                      type: string
                    player_color:
                      type: string
                      pattern: ^#[0-9A-Fa-f]{6}$
                    is_cover_overridable:
                      type: boolean
                    is_theme_overridable:
                      type: boolean
      responses:
        '200':
          description: Upload session created. When `track` was supplied in the request, also includes track_id, track, track_upload, and track_cover_upload.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    upload_session_id:
                      type: string
                      format: uuid
                    upload_session:
                      $ref: '#/components/schemas/UploadSession'
                    player_color:
                      type: string
                      nullable: true
                    player_color_light:
                      type: string
                      nullable: true
                    player_color_dark:
                      type: string
                      nullable: true
                    expires_at:
                      type: string
                      format: date-time
                    track_id:
                      type: string
                      format: uuid
                      description: Present only when the request included a nested `track` object.
                    track:
                      $ref: '#/components/schemas/Track'
                      description: Present only when the request included a nested `track` object.
                    track_upload:
                      $ref: '#/components/schemas/UploadHandle'
                      description: Present only when the request included a nested `track` object.
                    track_cover_upload:
                      $ref: '#/components/schemas/UploadHandle'
                      description: Present only when the request included a nested `track` object.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/upload_session/{upload_session_id}:
    get:
      tags:
      - Upload Sessions
      operationId: getUploadSession
      summary: Get upload session
      description: No authentication required — the session ID acts as the credential.
      security: []
      parameters:
      - name: upload_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Upload session details.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    upload_session_id:
                      type: string
                      format: uuid
                    upload_session:
                      $ref: '#/components/schemas/UploadSession'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/upload/{upload_session_id}/track:
    post:
      tags:
      - Upload Sessions
      operationId: createUploadSessionTrack
      summary: Create a track within an upload session
      description: Call once per file to obtain a per-track upload URL. Returns the full track object, including the delivery base_path/base_url that variant filenames append to. No authentication required — the session ID acts as the credential.
      security: []
      parameters:
      - name: upload_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - file_name
              properties:
                file_name:
                  type: string
                organization_index:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
                player_title:
                  type: string
                player_subtitle:
                  type: string
                player_color:
                  type: string
                  pattern: ^#[0-9A-Fa-f]{6}$
                is_cover_overridable:
                  type: boolean
                is_theme_overridable:
                  type: boolean
      responses:
        '200':
          description: Track and upload handle returned.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    upload_session_id:
                      type: string
                      format: uuid
                    track_id:
                      type: string
                      format: uuid
                    track:
                      $ref: '#/components/schemas/Track'
                    upload_session:
                      $ref: '#/components/schemas/UploadSession'
                    track_upload:
                      $ref: '#/components/schemas/UploadHandle'
                    track_cover_upload:
                      $ref: '#/components/schemas/UploadHandle'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - ok
      - message
      properties:
        ok:
          type: boolean
          const: false
        message:
          type: string
        api_request_id:
          type: string
          format: uuid
    OkEnvelope:
      type: object
      required:
      - ok
      - api_request_id
      properties:
        ok:
          type: boolean
          const: true
        api_request_id:
          type: string
          format: uuid
    UploadSession:
      type: object
      properties:
        id:
          type: string
          format: uuid
        creator_id:
          type: string
          format: uuid
        collection_id:
          type: string
          format: uuid
        organization_index:
          type: string
        metadata:
          type: object
          additionalProperties: true
        expires_at:
          type: string
          format: date-time
    Track:
      type: object
      properties:
        id:
          type: string
          format: uuid
        collection_id:
          type: string
          format: uuid
        creator_id:
          type: string
          format: uuid
        file_name:
          type: string
        duration:
          type: number
        organization_index:
          type: string
        metadata:
          type: object
          additionalProperties: true
        is_cover_overridable:
          type: boolean
        is_theme_overridable:
          type: boolean
        player_title:
          type: string
        player_subtitle:
          type: string
        player_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        player_color_light:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          readOnly: true
          description: Derived read-only variant of player_color adjusted to stay legible on a light background.
        player_color_dark:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          readOnly: true
          description: Derived read-only variant of player_color adjusted to stay legible on a dark background.
        transcription:
          type:
          - string
          - 'null'
          readOnly: true
          description: Plain-text transcription as paragraphs when transcription is enabled for the organization. Null when unavailable. Language is auto-detected unless provisioned otherwise. Transcription is not a self-serve / selectable variant — contact AudioDN if you need it.
        transcription_language:
          type:
          - string
          - 'null'
          readOnly: true
          description: BCP-47 language code of the spoken source language for `transcription` (from automatic language detection, or a provisioned language override). Null when unavailable.
        status:
          type: string
          enum:
          - initializing
          - processing
          - fallback_processing
          - ready
          - incomplete
          - failed
        base_path:
          type: string
          readOnly: true
          description: Durable delivery path prefix for this track's variant files. Each variant file is base_path plus its variant suffix and extension (e.g. `{base_path}_preview.mp3`).
        base_url:
          type: string
          format: uri
          readOnly: true
          description: 'Durable delivery URL prefix: base_path served from the organization''s unique audiodelivery.net subdomain. Append the variant suffix and extension, then sign for delivery (e.g. `{base_url}_128.mp3`).'
    UploadHandle:
      type: object
      properties:
        method:
          type: string
          enum:
          - PUT
          - POST
        upload_url:
          type: string
          format: uri
        ttl:
          type: integer
        expires_at:
          type: string
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Server-side API key. Use scoped client-side keys for browser and mobile contexts.