Manage Your Music Catalog via the UMW Recordings API

The UMW Recordings API gives you full programmatic control over your music catalog. From creating a new release to uploading high-resolution audio masters and artwork, every step of the catalog workflow is available through a consistent set of REST endpoints. This guide walks you through the complete process — from your first API call to submitting a release for distribution.

Catalog Object Model

Understanding how catalog objects relate to each other will help you structure your API calls correctly.

Release — The top-level catalog object. A release represents an album, EP, or single and holds metadata such as title, UPC, release date, and territories. Releases act as the container for all tracks and assets.
Track — An individual recording attached to a release. Each track carries its own ISRC, contributor credits, genre, language, and explicit content flags.
Asset — A binary file linked to either a release or a track. Asset types include audio masters (audio/wav, audio/flac) and cover artwork (image/jpeg, image/png). Assets move through a status lifecycle (uploading → processing → ready) before they can be used in a submission.

A release must have at least one track with a ready audio asset and one ready artwork asset before it can be submitted for delivery.

Step-by-Step: Building a Release

The release_date field must be set to a date at least 7 days in the future for standard submissions. Expedited delivery windows are available for qualifying label accounts — contact your UMW partner manager for details.

Create a Release

Start by creating the release record. This establishes the top-level metadata container and returns a release_id you will use throughout the rest of the workflow.

POST /v1/releases

Request body:

{
  "title": "Neon Meridian",
  "artists": [
    {
      "name": "Calloway Drift",
      "role": "primary",
      "apple_id": "1234567890",
      "spotify_id": "4tZwfgrHOc3mvqYlEYSvVi"
    }
  ],
  "release_date": "2024-09-20",
  "label_name": "Parallel Records",
  "catalog_number": "PAR-2024-041",
  "upc": "850123456789",
  "release_type": "album",
  "territories": ["WORLDWIDE"],
  "genre": "Electronic",
  "subgenre": "Ambient",
  "language": "en",
  "copyright_year": 2024,
  "copyright_text": "℗ 2024 Parallel Records",
  "recording_location": "Los Angeles, CA"
}

Response:

{
  "id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "status": "draft",
  "title": "Neon Meridian",
  "upc": "850123456789",
  "release_date": "2024-09-20",
  "label_name": "Parallel Records",
  "territories": ["WORLDWIDE"],
  "created_at": "2024-06-15T10:00:00Z",
  "updated_at": "2024-06-15T10:00:00Z"
}

Store the id value — you will reference it as release_id in subsequent calls.

Create and Attach Tracks

Create each track as an independent object, then attach it to the release. This two-step approach allows you to reuse track records across releases and manage ISRC registration separately from release composition.Create the track:

POST /v1/tracks

{
  "title": "Gradient Pulse",
  "version": "Album Version",
  "isrc": "USPAR2400101",
  "artists": [
    {
      "name": "Calloway Drift",
      "role": "primary"
    }
  ],
  "contributors": [
    {
      "name": "Mara Solano",
      "role": "producer"
    },
    {
      "name": "Calloway Drift",
      "role": "composer"
    },
    {
      "name": "Calloway Drift",
      "role": "lyricist"
    }
  ],
  "language": "en",
  "genre": "Electronic",
  "subgenre": "Ambient",
  "explicit": false,
  "duration_seconds": 214,
  "recording_year": 2024,
  "recording_country": "US",
  "copyright_text": "℗ 2024 Parallel Records"
}

Response:

{
  "id": "trk_01HXK5CD2PQRS3UVWX7YZ0AB1",
  "status": "draft",
  "title": "Gradient Pulse",
  "isrc": "USPAR2400101",
  "duration_seconds": 214,
  "created_at": "2024-06-15T10:05:00Z"
}

Attach the track to the release:

POST /v1/releases/{release_id}/tracks

{
  "track_id": "trk_01HXK5CD2PQRS3UVWX7YZ0AB1",
  "track_number": 1,
  "disc_number": 1
}

Repeat this process for each track on the release. Track numbers must be unique within a disc and sequential starting from 1.

Upload Assets

Assets are uploaded via multipart form data. You need at least one audio master per track and one piece of cover artwork per release.Upload an audio master:

POST /v1/assets
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="gradient_pulse_master.wav"
Content-Type: audio/wav

<binary audio data>
--boundary
Content-Disposition: form-data; name="asset_type"

audio
--boundary
Content-Disposition: form-data; name="track_id"

trk_01HXK5CD2PQRS3UVWX7YZ0AB1
--boundary
Content-Disposition: form-data; name="quality"

master
--boundary--

Upload cover artwork:

--boundary
Content-Disposition: form-data; name="file"; filename="neon_meridian_cover.jpg"
Content-Type: image/jpeg

<binary image data>
--boundary
Content-Disposition: form-data; name="asset_type"

artwork
--boundary
Content-Disposition: form-data; name="release_id"

rel_01HXK3AB7NMCPQ2XYZ9WD4EF5
--boundary--

Both upload calls return an asset object immediately with status: "uploading". Poll the asset endpoint until the status reaches ready before submitting:

GET /v1/assets/{asset_id}

Asset status lifecycle:

Status	Description
`uploading`	File transfer in progress
`processing`	UMW is validating format, loudness, and metadata
`ready`	Asset passed all checks and is available for submission
`failed`	Asset failed validation; see `validation_errors` for details

Sample ready asset response:

{
  "id": "ast_01HXK7EF3RSTU4VWXY8ZA1BC2",
  "status": "ready",
  "asset_type": "audio",
  "filename": "gradient_pulse_master.wav",
  "duration_seconds": 214,
  "sample_rate": 48000,
  "bit_depth": 24,
  "channels": 2,
  "loudness_lufs": -14.2,
  "track_id": "trk_01HXK5CD2PQRS3UVWX7YZ0AB1",
  "created_at": "2024-06-15T10:10:00Z",
  "updated_at": "2024-06-15T10:11:45Z"
}

Cover artwork must be a minimum of 3000 × 3000 pixels at 72 DPI, in sRGB color space. Audio masters must be 16-bit or 24-bit WAV or FLAC with a sample rate of 44.1 kHz or higher.

Review and Submit

Before submitting, you can update any release-level metadata using a PATCH request:

PATCH /v1/releases/{release_id}

{
  "release_date": "2024-09-27",
  "copyright_text": "℗ & © 2024 Parallel Records",
  "territories": ["US", "CA", "GB", "DE", "AU", "FR", "JP"]
}

Once all tracks have ready audio assets and the release has a ready artwork asset, submit the release for internal review:

POST /v1/releases/{release_id}/submit

Response:

{
  "id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "status": "validating",
  "submitted_at": "2024-06-15T11:00:00Z",
  "message": "Your release is under review. You will be notified when validation is complete."
}

The release status will transition from validating to ready once UMW’s systems have completed metadata and asset validation. You can subscribe to the release.status.changed webhook event to receive real-time updates rather than polling. See the Webhooks guide for setup instructions.

Release Status Reference

Status	Description
`draft`	Release is being assembled; edits are freely allowed
`validating`	Submitted for internal review; limited edits allowed
`ready`	Passed validation; eligible for delivery submission
`submitted`	Delivery order placed with one or more stores
`delivered`	Confirmed live on all target stores
`action_required`	One or more stores require metadata corrections
`rejected`	Release was rejected; see rejection details
`taken_down`	Release has been removed from all stores

Get Started

Platform Guides

Platform Reference

Manage Your Music Catalog via the UMW Recordings API

Catalog Object Model

Step-by-Step: Building a Release

Release Status Reference

​Catalog Object Model

​Step-by-Step: Building a Release

​Release Status Reference

Catalog Object Model

Step-by-Step: Building a Release

Release Status Reference