---
title: "Create upload session"
method: POST
path: "/v1/upload_session"
tags: ["Upload Sessions"]
---

# Create upload session

`POST /v1/upload_session`

## Request

- Base URL: `https://api.audiodelivery.net`
- URL: `https://api.audiodelivery.net/v1/upload_session`
- Auth: HTTP bearer

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).

## Request body

- object
  - `collection_id` string, uuid, required: Required unless the API key is scoped to a collection.
  - `creator_id` string, uuid
  - `organization_index` string
  - `metadata` object
  - `expires_in` integer: Session duration in seconds (default 3600, min 60, max 86400).
  - `track` object: When present, also create that track and append track upload fields to the response.
    - `file_name` string, required: Original filename of the track. Required when track is present.
    - `organization_index` string
    - `metadata` object
    - `player_title` string
    - `player_subtitle` string
    - `player_color` string
    - `is_cover_overridable` boolean
    - `is_theme_overridable` boolean

## Response `200`

Upload session created. When `track` was supplied in the request, also includes track_id, track, track_upload, and track_cover_upload.

- object
  - `ok` true, required
  - `api_request_id` string, uuid, required
  - `upload_session_id` string, uuid
  - `upload_session` UploadSession
    - `id` string, uuid
    - `creator_id` string, uuid
    - `collection_id` string, uuid
    - `organization_index` string
    - `metadata` object
    - `expires_at` string, date-time
  - `player_color` string, nullable
  - `player_color_light` string, nullable
  - `player_color_dark` string, nullable
  - `expires_at` string, date-time
  - `track_id` string, uuid: Present only when the request included a nested `track` object.
  - `track` Track
    - `id` string, uuid
    - `collection_id` string, uuid
    - `creator_id` string, uuid
    - `file_name` string
    - `duration` number
    - `organization_index` string
    - `metadata` object
    - `is_cover_overridable` boolean
    - `is_theme_overridable` boolean
    - `player_title` string
    - `player_subtitle` string
    - `player_color` string
    - `player_color_light` string: Derived read-only variant of player_color adjusted to stay legible on a light background.
    - `player_color_dark` string: Derived read-only variant of player_color adjusted to stay legible on a dark background.
    - `transcription` string, nullable: 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` string, nullable: BCP-47 language code of the spoken source language for `transcription` (from automatic language detection, or a provisioned language override). Null when unavailable.
    - `status` 'initializing' | 'processing' | 'fallback_processing' | 'ready' | 'incomplete' | 'failed'
    - `base_path` string: 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` string, uri: 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`).
  - `track_upload` UploadHandle
    - `method` 'PUT' | 'POST'
    - `upload_url` string, uri
    - `ttl` integer
    - `expires_at` string, date-time
  - `track_cover_upload` UploadHandle
    - `method` 'PUT' | 'POST'
    - `upload_url` string, uri
    - `ttl` integer
    - `expires_at` string, date-time

## Other responses

- `400`: Invalid parameters.
- `401`: Missing or invalid API key.

---

[API](https://skmtc.dev/audiodeliverynetwork/apis/audiodn-api.md) · [All operations](https://skmtc.dev/audiodeliverynetwork/apis/audiodn-api/llms.txt) · [OpenAPI document](https://skmtc.dev/audiodeliverynetwork/apis/audiodn-api/revisions/57d355fc6a44?raw)