Audio Delivery Network Tracks API

openapi: 3.2.0
info:
  title: AudioDN Tracks 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: Tracks
paths:
  /v1/collection/{collection_id}/track:
    get:
      tags:
      - Tracks
      operationId: listCollectionTracks
      summary: List tracks in a collection
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Tracks list.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    count:
                      type: integer
                    tracks:
                      type: array
                      items:
                        $ref: '#/components/schemas/Track'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/track:
    post:
      tags:
      - Tracks
      operationId: createTrack
      summary: Create a track
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - collection_id
              - file_name
              properties:
                collection_id:
                  type: string
                  format: uuid
                  description: Required unless the API key is scoped to a collection.
                creator_id:
                  type: string
                  format: uuid
                file_name:
                  type: string
                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}$
      responses:
        '200':
          description: Track created.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    track_id:
                      type: string
                      format: uuid
                    track:
                      $ref: '#/components/schemas/Track'
                    track_upload:
                      $ref: '#/components/schemas/UploadHandle'
                    track_cover_upload:
                      $ref: '#/components/schemas/UploadHandle'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/track/{track_id}:
    get:
      tags:
      - Tracks
      operationId: getTrack
      summary: Get track
      parameters:
      - name: track_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Track details.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    track_id:
                      type: string
                      format: uuid
                    track:
                      $ref: '#/components/schemas/Track'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Tracks
      operationId: updateTrack
      summary: Update track
      parameters:
      - name: track_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Track'
      responses:
        '200':
          description: Updated track.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    track_id:
                      type: string
                      format: uuid
                    track:
                      $ref: '#/components/schemas/Track'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Tracks
      operationId: deleteTrack
      summary: Delete track
      parameters:
      - name: track_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Track deleted.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    track_id:
                      type: string
                      format: uuid
                    deleted_track:
                      $ref: '#/components/schemas/Track'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
  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
    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.