Audio Delivery Network Play Sessions API

openapi: 3.2.0
info:
  title: AudioDN Play 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: Play Sessions
paths:
  /v1/play_session/{scope}:
    post:
      tags:
      - Play Sessions
      operationId: createPlaySession
      summary: Create play session
      parameters:
      - name: scope
        in: path
        required: true
        schema:
          type: string
          enum:
          - collection
          - track
        description: '"collection" or "track". "playlist" is reserved for a future release and currently returns 400.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - variants
              properties:
                variants:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  description: Non-empty list of variant indexes for the play session.
                collection_id:
                  type: string
                  format: uuid
                  description: Required when scope is 'collection', unless the API key is scoped to a collection.
                track_id:
                  type: string
                  format: uuid
                  description: Required when scope is 'track', unless the API key is scoped to a track.
                is_downloadable:
                  type: boolean
                  description: Requests downloadable tracks. Only honored when the API key also allows downloads; the stored value is api_key.is_downloadable AND this request.
                expires_in:
                  type: integer
                  description: Session duration in seconds (default 3600, min 60, max 86400).
                  minimum: 60
                  maximum: 86400
                  default: 3600
      responses:
        '200':
          description: Play session created.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    play_session_id:
                      type: string
                      format: uuid
                    play_session:
                      $ref: '#/components/schemas/PlaySession'
                    tracks:
                      type: array
                      items:
                        $ref: '#/components/schemas/Track'
                    first_track:
                      type: object
                      additionalProperties: true
                      description: Full playback data for the first track, including signed variant URLs, so a player can render without a second call.
                    expires_at:
                      type: string
                      format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/play_session/{play_session_id}:
    get:
      tags:
      - Play Sessions
      operationId: getPlaySession
      summary: Get play session
      parameters:
      - name: play_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Play session details.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    play_session_id:
                      type: string
                      format: uuid
                    play_session:
                      $ref: '#/components/schemas/PlaySession'
                    tracks:
                      type: array
                      items:
                        $ref: '#/components/schemas/Track'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/play/{play_session_id}/{play_track_id}:
    get:
      tags:
      - Play Sessions
      operationId: getPlayTrack
      summary: Get a track within a play session
      description: No authentication required — the session ID acts as the credential.
      security: []
      parameters:
      - name: play_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: play_track_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Track within the play session, including signed variant URLs.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    play_session_id:
                      type: string
                      format: uuid
                    track_id:
                      type: string
                      format: uuid
                    play_session:
                      $ref: '#/components/schemas/PlaySession'
                    cover_image:
                      type: string
                      format: uri
                    track:
                      $ref: '#/components/schemas/Track'
                    levels:
                      type: object
                      additionalProperties: true
                    variants:
                      type: array
                      items:
                        type: object
                        properties:
                          path:
                            type: string
                            format: uri
                          url:
                            type: string
                            format: uri
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/play/{play_session_id}/{play_track_id}/{variant_index}/download:
    get:
      tags:
      - Play Sessions
      operationId: downloadPlayTrackVariant
      summary: Download a variant of a track within a play session
      description: Returns a short-lived signed download URL for a specific variant. Only available when the session's stored is_downloadable is true; otherwise returns 403. No authentication required — the session ID acts as the credential.
      security: []
      parameters:
      - name: play_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: play_track_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: variant_index
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Signed download URL.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    download:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                        expires_at:
                          type: string
                          format: date-time
        '403':
          description: The session is not downloadable.
        '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:
    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`).'
    PlaySession:
      type: object
      properties:
        id:
          type: string
          format: uuid
        creator_id:
          type: string
          format: uuid
        organization_index:
          type: string
        metadata:
          type: object
          additionalProperties: true
        variants:
          type: array
          items:
            type: string
        is_downloadable:
          type: boolean
        expires_at:
          type: string
          format: date-time
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Server-side API key. Use scoped client-side keys for browser and mobile contexts.