Releases API — Create, Update, and Submit Releases

A Release is the primary container in the UMW platform. It represents a distributable music product — an album, EP, single, or compilation — and acts as the authoritative record that groups your tracks, assets, and delivery metadata into a single submission unit. Every track you distribute must belong to a release, and every release moves through a defined lifecycle (from draft to delivered) before it reaches digital stores and streaming platforms. You manage release-level metadata here, including UPC, territory rights, and label attribution.

The Release Object

string

Unique identifier for the release. Prefixed with rel_.

string

The commercial title of the release as it will appear in stores.

array

An ordered array of artist objects associated with this release.

Show Artist object fields

string

The display name of the artist.

string

The artist’s role. Common values: main, featured, remixer.

string

The commercial release date in ISO 8601 format (YYYY-MM-DD).

string

The name of the record label or rights holder to display on storefronts.

string

The Universal Product Code (UPC) assigned to this release. If omitted on creation, the platform auto-assigns one.

array

An array of ISO 3166-1 alpha-2 country codes defining where the release is licensed for distribution. Pass ["WORLD"] to indicate worldwide rights.

enum

The current lifecycle state of the release. Possible values: draft, submitted, delivered, rejected.

string

ISO 8601 timestamp of when the release was created.

string

ISO 8601 timestamp of the most recent update to the release record.

POST /v1/releases

Create a new release. All newly created releases start in draft status, giving you time to attach tracks and assets before submission. You must provide at least a title, one entry in artists, and a release_date to create a valid draft.

Request parameters

string

required

The commercial title of the release. Maximum 500 characters.

array

required

An ordered array of artist objects. At least one artist with role: "main" is required.

Show Artist object fields

string

required

The display name of the artist.

string

required

The artist’s role on this release. Accepted values: main, featured, remixer, various.

string

required

The intended commercial release date in ISO 8601 format (YYYY-MM-DD). Must be a future date at submission time.

string

The label or rights-holder name to display on storefronts. Defaults to the label name configured on your UMW account.

array

Array of ISO 3166-1 alpha-2 country codes. Defaults to ["WORLD"] if omitted.

string

A valid 12-digit UPC. If omitted, the platform automatically assigns a UPC from your allocated pool.

Example request

curl https://api.umwrecordingsinc.com/v1/releases \
  -X POST \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Midnight Sessions",
    "artists": [{"name": "Aria Vance", "role": "main"}],
    "release_date": "2024-08-01",
    "label_name": "Solstice Records",
    "territories": ["US", "GB", "DE", "AU"],
    "upc": "012345678901"
  }'

{
  "title": "Midnight Sessions",
  "artists": [{"name": "Aria Vance", "role": "main"}],
  "release_date": "2024-08-01",
  "label_name": "Solstice Records",
  "territories": ["US", "GB", "DE", "AU"],
  "upc": "012345678901"
}

Example response

201 Created

{
  "id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "title": "Midnight Sessions",
  "artists": [
    {
      "name": "Aria Vance",
      "role": "main"
    }
  ],
  "release_date": "2024-08-01",
  "label_name": "Solstice Records",
  "upc": "012345678901",
  "territories": ["US", "GB", "DE", "AU"],
  "status": "draft",
  "created_at": "2024-04-12T09:15:00Z",
  "updated_at": "2024-04-12T09:15:00Z"
}

GET /v1/releases/{release_id}

Retrieve the full details of a single release by its ID.

Path parameters

string

required

The unique identifier of the release. Example: rel_01HXK3AB7NMCPQ2XYZ9WD4EF5.

Example request

cURL

curl https://api.umwrecordingsinc.com/v1/releases/rel_01HXK3AB7NMCPQ2XYZ9WD4EF5 \
  -H "Authorization: Bearer $UMW_API_KEY"

Example response

200 OK

{
  "id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "title": "Midnight Sessions",
  "artists": [
    {
      "name": "Aria Vance",
      "role": "main"
    }
  ],
  "release_date": "2024-08-01",
  "label_name": "Solstice Records",
  "upc": "012345678901",
  "territories": ["US", "GB", "DE", "AU"],
  "status": "draft",
  "created_at": "2024-04-12T09:15:00Z",
  "updated_at": "2024-04-12T09:15:00Z"
}

PATCH /v1/releases/{release_id}

Update the metadata of an existing release. You can modify any combination of the fields below in a single request — only the fields you include are changed.

Only releases in draft status can be updated. If a release has already been submitted, you cannot modify it in place. To make corrections, contact your UMW account manager to revert the release to draft, or create a new draft release.

Path parameters

string

required

The unique identifier of the release to update.

Request parameters

string

Updated commercial title for the release.

string

Updated commercial release date in ISO 8601 format (YYYY-MM-DD).

array

Replacement array of ISO 3166-1 alpha-2 territory codes. This field is replaced in full — it is not merged with the existing value.

string

Updated label or rights-holder name.

string

The ID of a ready artwork asset to associate with this release. See the Assets API for upload instructions. This artwork is delivered to all storefronts alongside the release’s tracks.

Example request

curl https://api.umwrecordingsinc.com/v1/releases/rel_01HXK3AB7NMCPQ2XYZ9WD4EF5 \
  -X PATCH \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "release_date": "2024-09-15",
    "territories": ["US", "GB", "DE", "AU", "CA", "FR"]
  }'

{
  "release_date": "2024-09-15",
  "territories": ["US", "GB", "DE", "AU", "CA", "FR"]
}

Example response

200 OK

{
  "id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "title": "Midnight Sessions",
  "artists": [
    {
      "name": "Aria Vance",
      "role": "main"
    }
  ],
  "release_date": "2024-09-15",
  "label_name": "Solstice Records",
  "upc": "012345678901",
  "territories": ["US", "GB", "DE", "AU", "CA", "FR"],
  "status": "draft",
  "created_at": "2024-04-12T09:15:00Z",
  "updated_at": "2024-04-14T11:42:00Z"
}

POST /v1/releases/{release_id}/submit

Submit a release for delivery review. Once submitted, the UMW platform validates all attached tracks and assets and routes the release to the delivery pipeline for store ingestion. The release status transitions from draft to submitted upon a successful call. Before submitting, ensure that:

At least one track is attached to the release
Every attached track has an audio_asset_id pointing to a ready asset
The release has an artwork asset in ready status
The release_date is in the future

Include an Idempotency-Key header on submission requests to safely retry in the event of a network timeout or ambiguous response. The platform will return the original response for any duplicate submission with the same key within 24 hours.

Path parameters

string

required

The unique identifier of the release to submit.

Example request

cURL

curl https://api.umwrecordingsinc.com/v1/releases/rel_01HXK3AB7NMCPQ2XYZ9WD4EF5/submit \
  -X POST \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -H "Idempotency-Key: idem_submit_rel_01HXK3AB7NMCPQ2XYZ9WD4EF5_v1"

Example response

200 OK

{
  "id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "title": "Midnight Sessions",
  "artists": [
    {
      "name": "Aria Vance",
      "role": "main"
    }
  ],
  "release_date": "2024-09-15",
  "label_name": "Solstice Records",
  "upc": "012345678901",
  "territories": ["US", "GB", "DE", "AU", "CA", "FR"],
  "status": "submitted",
  "created_at": "2024-04-12T09:15:00Z",
  "updated_at": "2024-04-15T08:00:00Z"
}

GET /v1/releases

Retrieve a paginated list of releases in your catalog. Results are returned in reverse chronological order by created_at. Use the status filter to narrow results to a specific lifecycle stage, and use cursor-based pagination to page through large catalogs efficiently.

Query parameters

string

Filter results to releases matching the given status. Accepted values: draft, submitted, delivered, rejected. Omit to return releases of all statuses.

integer

The number of results to return per page. Defaults to 20. Maximum value is 100.

string

An opaque pagination cursor returned as next_cursor in a previous response. Pass this value to retrieve the next page of results.

Example request

cURL

curl "https://api.umwrecordingsinc.com/v1/releases?status=draft&limit=2" \
  -H "Authorization: Bearer $UMW_API_KEY"

Example response

200 OK

{
  "data": [
    {
      "id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
      "title": "Midnight Sessions",
      "artists": [{"name": "Aria Vance", "role": "main"}],
      "release_date": "2024-09-15",
      "label_name": "Solstice Records",
      "upc": "012345678901",
      "territories": ["US", "GB", "DE", "AU", "CA", "FR"],
      "status": "draft",
      "created_at": "2024-04-12T09:15:00Z",
      "updated_at": "2024-04-14T11:42:00Z"
    },
    {
      "id": "rel_01HWZP9KL4MNRQ8XYZ5BV2JD3",
      "title": "Northern Lights EP",
      "artists": [{"name": "Caden Reyes", "role": "main"}],
      "release_date": "2024-10-01",
      "label_name": "Solstice Records",
      "upc": "098765432109",
      "territories": ["WORLD"],
      "status": "draft",
      "created_at": "2024-04-10T14:30:00Z",
      "updated_at": "2024-04-10T14:30:00Z"
    }
  ],
  "next_cursor": "cur_01HXK9MN5PQRST6UV7WXY8Z0B",
  "has_more": true
}

When has_more is false, you have reached the last page of results. The next_cursor field will be null.

Catalog

Distribution

Finance

Platform

Releases API — Create, Update, and Submit Releases

The Release Object

POST /v1/releases

Request parameters

Example request

Example response

GET /v1/releases/{release_id}

Path parameters

Example request

Example response

PATCH /v1/releases/{release_id}

Path parameters

Request parameters

Example request

Example response

POST /v1/releases/{release_id}/submit

Path parameters

Example request

Example response

GET /v1/releases

Query parameters

Example request

Example response

​The Release Object

​POST /v1/releases

​Request parameters

​Example request

​Example response

​GET /v1/releases/{release_id}

​Path parameters

​Example request

​Example response

​PATCH /v1/releases/{release_id}

​Path parameters

​Request parameters

​Example request

​Example response

​POST /v1/releases/{release_id}/submit

​Path parameters

​Example request

​Example response

​GET /v1/releases

​Query parameters

​Example request

​Example response

The Release Object

POST /v1/releases

Request parameters

Example request

Example response

GET /v1/releases/{release_id}

Path parameters

Example request

Example response

PATCH /v1/releases/{release_id}

Path parameters

Request parameters

Example request

Example response

POST /v1/releases/{release_id}/submit

Path parameters

Example request

Example response

GET /v1/releases

Query parameters

Example request

Example response