Uploads
Upload behavior is one of the highest-risk parts of catalog integration. A client should know when an upload is complete, which reference to store, and what is safe to retry.
Audio upload limits
| Rule | Value |
|---|---|
| Accepted audio extensions | wav, mp3, flac, m4a, aac, aif, aiff |
| Maximum audio file size | 500 MB |
| Minimum audio duration | 60 seconds |
| Required content | A readable audio stream matching the file extension. |
| Returned temporary reference | audio_file_id |
The upload endpoint verifies audio metadata. Files that cannot be read, do not contain audio, do not match their extension, exceed the size limit, or are shorter than the minimum duration fail validation.
Complete file upload
Use POST /api/v1/tracks/upload when the customer system can send the whole file in one multipart request.
curl --request POST 'https://enterprise.spacemedia.uk/api/v1/tracks/upload' \
--header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
--header 'X-User-Id: 9d7046b2-3ab1-4c9d-9bd8-90bbd22b7df2' \
--form 'track=@midnight-atlas-master.wav;type=audio/wav'Every upload route requires X-User-Id, including the status read used for recovery. Use the same value for the upload and for the track create that follows it.
Store audio_file_id from the response and use it when creating the track. Do not treat audio_file_id as the stable track reference.
Chunked upload
Use POST /api/v1/tracks/upload/chunk when a client needs to send a large file in pieces.
| Field | Rule |
|---|---|
upload_session_id | Optional stable client-generated session reference. Send one and use the same value for every chunk so the upload can be resumed safely. |
chunk_index | Zero-based chunk number. The first chunk is 0. |
total_chunks | Total number of chunks expected for the file. Maximum 64, so size your chunks to fit the file rather than to a fixed small value. |
file_name | Original file name with an accepted audio extension. |
file_size | Full file size in bytes. |
chunk | Binary chunk file. Each chunk can be up to 8 MB. |
The API returns upload_session_id and complete: false while it is still waiting for more chunks. It returns complete: true and audio_file_id after every chunk is received, assembled, and validated.
With 8 MB chunks and a 64-chunk ceiling, one chunked upload covers a file up to about 512 MB, which matches the 500 MB audio limit. Run at most 3 upload sessions per user and 25 per organization at once; further sessions are rejected until an active one finishes.
Recover upload status
Call GET /api/v1/tracks/upload/{upload_session_id} after a timeout, reconnect, or lost final response. Use the same value that was sent as upload_session_id.
- When
completeisfalse, comparereceived_chunkswithtotal_chunksand resend only missing chunks. - When
completeistrue, store the returnedaudio_file_idand continue with track creation. - A
404means the session is unknown to the current user and organization, or its recovery window has expired. Start a new upload session.
Upload status and completed receipts are scoped to the authenticated user and organization. A different user cannot use this endpoint to discover or claim another user's upload.
Retry behavior
| Failure | Safe action |
|---|---|
| Complete upload fails before a response | Retry the same file once network health is restored. |
| Chunk upload fails before a response | Check upload status, then retry the same chunk with the same upload_session_id and chunk_index only if it is missing. |
| Final chunk returns validation errors | Fix the source file or chunking logic, then start a new upload session. |
| Track create fails after upload | Reuse the successful audio_file_id if the failure was unrelated to the audio file. |
If a client is unsure whether the final chunk completed, query upload status. Do not create a track until the API has returned audio_file_id.
Cover art
Release create and update requests use multipart form data when cover_art is uploaded.
The upload validator accepts JPG, PNG, or WEBP. Use an original JPG or PNG for a release that will be delivered to stores; a WEBP upload can be accepted by the editor but is not a delivery master.
Cover art should be:
- Original JPG or PNG for delivery. WEBP is suitable only for non-delivery editing workflows.
- Square.
- Between 3000x3000 and 5000x5000 pixels where release validation applies.
- Free of URLs, pricing, store badges, and temporary promo text.
Attachment order
- Upload audio.
- Store
audio_file_id. - Create track with
audio_file_id. - Store returned
track_id. - Attach, order, update, or document the track with
track_id.
See Release Lifecycle for the full catalog flow.
Common questions
What is the difference between audio_file_id and track_id?
audio_file_id is a temporary reference to an uploaded file. track_id is the stable catalog reference returned after the track is created. Never store the first where you mean the second.
When is it safe to create the track?
Only after the API has returned audio_file_id. If you are unsure whether the final chunk landed, query upload status first.
My upload session returns 404. What happened?
The session is unknown to the current user and organization, or its recovery window has expired. Start a new upload session.
Can I upload WEBP cover art for a release going to stores? Use an original JPG or PNG for delivery. The editor accepts WEBP, but it is not a delivery master.
Was this page helpful?