Release Lifecycle

The release lifecycle is the main catalog workflow for API integrations.

Before implementing this flow, review the Reference Values, Uploads, Metadata Style Guide, Delivery Statuses, and Rate Limits and Retries. These pages prevent the most common production blockers: bad metadata, duplicate submissions, unsafe polling, and unclear delivery states.

Recommended sequence

1. Create or reuse artist profiles.
2. Create the release shell with title, cover_art, format, and artists.
3. Upload audio and keep the returned audio_file_id.
4. Create tracks with title, audio_file_id, artists, language, primary_genre, credits, ISRC/ISWC, rights holder, and audio links.
5. Attach or reorder tracks on the release.
6. Update license metadata and territories.
7. Update distribution channels.
8. Run release review checks.
9. Submit the release when no blocking issues remain.

Minimal flow

Every catalog write below needs X-User-Id, the public user_id of the same-organization user the record belongs to. Without it the API returns 403. See Acting for Users for the full list and the read endpoints where the header is optional.

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/artists' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'X-User-Id: 9d7046b2-3ab1-4c9d-9bd8-90bbd22b7df2' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Nova Vale","spotify_id":"3q7HBObVc0L8jNeTe5Gofh"}'

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/releases' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'X-User-Id: 9d7046b2-3ab1-4c9d-9bd8-90bbd22b7df2' \
  --form 'title=Midnight Atlas' \
  --form 'format=single' \
  --form 'label=Night Shift Records' \
  --form 'genre=Electronic' \
  --form 'language=English' \
  --form 'artists[0][artist_id]=6f209ac7-d82c-4c8f-9d3e-bfe39c0df802' \
  --form 'artists[0][type]=Primary Artist' \
  --form 'cover_art=@midnight-atlas-cover.jpg;type=image/jpeg'

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'

Use the returned audio_file_id when creating the track. Reserve track_id for the stable track reference returned after track creation.

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/tracks' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'X-User-Id: 9d7046b2-3ab1-4c9d-9bd8-90bbd22b7df2' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Midnight Atlas",
    "release_id": "b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8",
    "audio_file_id": "audio_1783157400_6f9c2b8e4d1a",
    "artists": [
      {
        "artist_id": "6f209ac7-d82c-4c8f-9d3e-bfe39c0df802",
        "type": "Primary Artist"
      },
      {
        "artist_id": "28636f32-61a4-41b8-8af4-70813049b9aa",
        "type": "Composer"
      }
    ],
    "language": "English",
    "license_holder_year": 2026,
    "license_holder_name": "Night Shift Records Ltd",
    "links": ["https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav"]
  }'

For the release create request, send multipart form data when uploading cover_art. The artists field takes public artist_id values, and every entry needs a type from the artist role list. Roles are display labels, so send Primary Artist, not primary. At least one entry must be Primary Artist or the request is rejected.

title and label are capped at 64 characters. label, genre, language, format, and cover_art are all required alongside title and artists. The release date is not set here: save it as digital_release_date on the license request below.

Readiness checks on GET /api/v1/releases/{release_id}/pre-qc are pre-submission validation. Release review queues under /api/v1/qc/releases/* are for permitted admins who already have dashboard access to review submitted releases.

Complete release handoff

After release and track creation, save rights, distribution, readiness, and submission in this order.

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/releases/b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8/license' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{
    "price_category": "mid",
    "digital_release_date": "2026-08-21",
    "original_release_date": "2026-08-21",
    "license_type": "copyright",
    "license_holder_year": 2026,
    "license_holder_name": "Night Shift Records Ltd",
    "sound_recordings_copyright_year": 2026,
    "sound_recordings_copyright_name": "Night Shift Records Ltd",
    "territories": ["GB", "US", "DE", "NL"]
  }'

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/releases/b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8/distribution' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{
    "channels": ["spotify", "apple_music", "youtube_music"],
    "territories": ["GB", "US", "DE", "NL"]
  }'

curl 'https://enterprise.spacemedia.uk/api/v1/releases/b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8/pre-qc' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e'

Read the readiness response before submission:

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/releases/b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8/submit' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e'

After submission, store release_id, review_id when returned, review_status, delivery_status, and submitted_at. If the submit request times out, fetch the release and review state before sending submit again.

On staging, complete the same submission and review sequence. Approval is simulated locally and never reaches a DSP. Store and inspect delivery_simulated; a value of true confirms a staging contract rehearsal, not storefront availability. Staging release media expires after the documented retention period, so integrations should keep their own fixture files.

Submission guardrails

• Cover art should be square and production quality.
• At least one Primary Artist is required.
• Tracks should include required contributor and rights metadata.
• Distribution channels should use supported channel codes such as spotify, apple_music, and youtube_music.
• Submit only after release review returns no blocking issues.
• After a timeout, fetch the release and review state before submitting again.
• Treat sent as delivery progress, not guaranteed live availability on every DSP.

Common questions

Where do most integrations go wrong? Two places. Attaching an audio_file_id before the upload confirmed success, and resubmitting after a timeout without first reading the release and review state.

Can I skip the readiness check and submit directly? The call will fail on anything blocking, but you lose the itemized list of what to fix. Run pre-qc first and let it tell you.

Which reference do I keep? release_id and track_id. audio_file_id is temporary and only valid until the track is created.

What is the difference between pre-qc and the review queues? pre-qc is your own pre-submission validation. The /api/v1/qc/releases/* queues are for permitted admins reviewing releases that have already been submitted.

Does an approved release mean it is live? No. Approval moves it into delivery. See Delivery Statuses.