API reference

Releases

Releases: drafts with their tracks, one at a time or many.

On this page

List releases
Create a draft release
Read a release with its tracks
Change a draft release
Archive a draft release
Create many draft releases

Base address https://api.stillmoregroup.com/api/v1. Every answer is JSON; errors have one shape.

Endpoint	What it does
`GET /releases`	List releases
`POST /releases`	Create a draft release
`GET /releases/{releaseId}`	Read a release with its tracks
`PATCH /releases/{releaseId}`	Change a draft release
`DELETE /releases/{releaseId}`	Archive a draft release
`POST /releases/batch`	Create many draft releases

List releases#

GET /releases · scope releases:read

Newest first. Filter by status, label, artist, UPC or your externalId; updatedSince returns what changed since your last sync.

Query parameters#

limitinteger: From 1 to 100. Default 25.
cursorstring: nextCursor from the previous page. Up to 200 characters.
updatedSincestring (date-time): Only records changed at or after this ISO 8601 time.
externalIdstring: Your own identifier for this record, unique within the organization. 1 to 100 characters.
statusstring: One of DRAFT, LABEL_REVIEW, IN_REVIEW, CHANGES_REQUESTED, REJECTED, APPROVED, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN, ARCHIVED.
labelIdstring: An id.
artistIdstring: An id.
upcstring: Up to 20 characters.

Headers#

Stillmore-Organization: A sub-label to act for, when the key may (see Sub-labels).

Example request#

curl "https://api.stillmoregroup.com/api/v1/releases?limit=25" \
  -H "Authorization: Bearer $STILLMORE_API_KEY"

Response 200#

A page: data holds the items below, hasMore says whether another page follows, and nextCursor is the cursor for it.

idstring
labelIdstring
titlestring
versionTitlestring or null
typestring: One of SINGLE, EP, ALBUM.
statusstring: Where the release is, review and delivery together. One of DRAFT, LABEL_REVIEW, IN_REVIEW, CHANGES_REQUESTED, REJECTED, APPROVED, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN, ARCHIVED.
primaryArtistIdsstring[]
featuredArtistIdsstring[]

Show 66 more fields

primaryGenrestring or null
secondaryGenrestring or null
languagestring or null
explicitboolean
releaseDatestring (date) or null
originalReleaseDatestring (date) or null
copyrightobject
copyright.cLineobject
copyright.pLineobject
territoriesobject
territories.modestring: One of WORLDWIDE, CUSTOM.
territories.codesstring[]
storesobject
stores.modestring: One of ALL, CUSTOM.
stores.codesstring[]
upcstring or null
artworkobject or null: The cover; null until one is uploaded.
artwork.statusstring: One of PENDING_UPLOAD, UPLOADED, VERIFIED, FAILED, DELETED.
artwork.fileNamestring or null
artwork.mimeTypestring or null
artwork.sizeBytesnumber or null
artwork.uploadedAtstring or null: ISO 8601 timestamp in UTC.
artwork.widthnumber or null
artwork.heightnumber or null
trackCountinteger: From -9007199254740991 to 9007199254740991.
tracksobject[]: Included when one release is read, created or changed.
tracks[].idstring
tracks[].releaseIdstring
tracks[].positioninteger: From -9007199254740991 to 9007199254740991.
tracks[].titlestring
tracks[].versionTitlestring or null
tracks[].primaryArtistIdsstring[]
tracks[].featuredArtistIdsstring[]
tracks[].explicitboolean
tracks[].isCoverboolean
tracks[].languagestring or null
tracks[].isrcstring or null
tracks[].lyricsstring or null
tracks[].creditsobject
tracks[].audioobject or null: The master; null until one is uploaded.
tracks[].externalIdstring or null: Your own id for it, when you set one.
tracks[].metadatamap of string: Your own keys and values, as you sent them.
tracks[].createdAtstring: ISO 8601 timestamp in UTC.
tracks[].updatedAtstring: ISO 8601 timestamp in UTC.
tracks[].revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.
reviewobject: Included when one release is read, created or changed.
review.submittedAtstring or null: ISO 8601 timestamp in UTC.
review.decidedAtstring or null: ISO 8601 timestamp in UTC.
review.automaticboolean: The account's automatic approval passed the release without a person.
review.notestring or null: What review asked for when it sent the release back, or why it rejected it.
review.issuesobject[]
review.documentsRequestedobject or null
deliveryobject: On its way to the stores, codes and store pages; included when one release is read, created or changed.
delivery.statusstring: One of NOT_SENT, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN.
delivery.sentAtstring or null
delivery.liveAtstring or null
delivery.refusedReasonstring or null
delivery.storeLinksobject[]
delivery.smartLinkobject or null
submittedAtstring or null: ISO 8601 timestamp in UTC.
approvedAtstring or null: ISO 8601 timestamp in UTC.
externalIdstring or null: Your own id for it, when you set one.
metadatamap of string: Your own keys and values, as you sent them.
createdAtstring: ISO 8601 timestamp in UTC.
updatedAtstring: ISO 8601 timestamp in UTC.
revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.

Example response

{
  "data": [
    {
      "id": "6731c2a1b3c4d5e6f7a8b9c0",
      "labelId": "6731c2a1b3c4d5e6f7a8b9c0",
      "title": "Night Signals",
      "versionTitle": "Radio Edit",
      "type": "SINGLE",
      "status": "DRAFT",
      "primaryArtistIds": [
        "6731c2a1b3c4d5e6f7a8b9c0"
      ],
      "featuredArtistIds": [
        "6731c2a1b3c4d5e6f7a8b9c0"
      ],
      "primaryGenre": "Pop",
      "secondaryGenre": "Pop",
      "language": "en",
      "explicit": false,
      "releaseDate": "2027-01-15",
      "originalReleaseDate": "2026-10-01",
      "copyright": {
        "cLine": {
          "year": 2026,
          "holder": "North Records"
        },
        "pLine": {
          "year": 2026,
          "holder": "North Records"
        }
      },
      "territories": {
        "mode": "WORLDWIDE",
        "codes": [
          "123456"
        ]
      },
      "stores": {
        "mode": "ALL",
        "codes": [
          "123456"
        ]
      },
      "upc": "0612345678905",
      "artwork": {
        "status": "PENDING_UPLOAD",
        "fileName": "cover.jpg",
        "mimeType": "…",
        "sizeBytes": 2483117,
        "uploadedAt": "2026-11-01T09:30:00.000Z",
        "width": 1,
        "height": 1
      },
      "trackCount": 1200,
      "tracks": [
        {
          "id": "6731c2a1b3c4d5e6f7a8b9c0",
          "releaseId": "6731c2a1b3c4d5e6f7a8b9c0",
          "position": 1,
          "title": "Night Signals",
          "versionTitle": "Radio Edit",
          "primaryArtistIds": [
            "6731c2a1b3c4d5e6f7a8b9c0"
          ],
          "featuredArtistIds": [
            "6731c2a1b3c4d5e6f7a8b9c0"
          ],
          "explicit": false,
          "isCover": false,
          "language": "en",
          "isrc": "GBXYZ2600001",
          "lyrics": "…",
          "credits": {
            "songwriters": [],
            "composers": [],
            "producers": [],
            "publishers": [],
            "mixers": [],
            "masteringEngineers": [],
            "remixers": []
          },
          "audio": {
            "status": "PENDING_UPLOAD",
            "fileName": "cover.jpg",
            "mimeType": "…",
            "sizeBytes": 2483117,
            "uploadedAt": "2026-11-01T09:30:00.000Z",
            "durationSeconds": 214,
            "sampleRate": 1,
            "bitDepth": 1,
            "channels": 1
          },
          "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
          "metadata": {
            "catalogueId": "1042"
          },
          "createdAt": "2026-11-01T09:30:00.000Z",
          "updatedAt": "2026-11-01T09:30:00.000Z",
          "revision": "…"
        }
      ],
      "review": {
        "submittedAt": "2026-11-01T09:30:00.000Z",
        "decidedAt": "2026-11-01T09:30:00.000Z",
        "automatic": false,
        "note": "Sent from our catalogue system",
        "issues": [
          {
            "category": "…",
            "message": "Sent from our catalogue system"
          }
        ],
        "documentsRequested": {
          "note": "Sent from our catalogue system",
          "requestedAt": "2026-11-01T09:30:00.000Z",
          "fulfilled": false
        }
      },
      "delivery": {
        "status": "NOT_SENT",
        "sentAt": "2026-11-01T09:30:00.000Z",
        "liveAt": "2026-11-01T09:30:00.000Z",
        "refusedReason": "Sent from our catalogue system",
        "storeLinks": [
          {
            "store": "Spotify",
            "url": "https://example.com/webhooks/stillmore"
          }
        ],
        "smartLink": {
          "url": "https://example.com/webhooks/stillmore",
          "enabled": true
        }
      },
      "submittedAt": "2026-11-01T09:30:00.000Z",
      "approvedAt": "2026-11-01T09:30:00.000Z",
      "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
      "metadata": {
        "catalogueId": "1042"
      },
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z",
      "revision": "…"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Create a draft release#

POST /releases · scope releases:write

Creates the draft and, when tracks is given, its tracks in order. A SINGLE always has exactly one track, created with the release.

Body#

labelIdstring: The organization's own label when left out. An id.
titlestringRequired: 1 to 180 characters.
versionTitlestring: Up to 120 characters.
typestring: SINGLE by default. One of SINGLE, EP, ALBUM.
primaryArtistIdsstring[]Required: 1 to 20 items.
featuredArtistIdsstring[]: Up to 20 items.
primaryGenrestring: A genre name from GET /v1/reference.
secondaryGenrestring: A genre name from GET /v1/reference.
languagestring: An ISO 639-1 code ("en") or a language name from GET /v1/reference.
explicitboolean: Explicit lyrics or content; new releases and tracks start with false.
releaseDatestring (date): The day it goes live in the stores; needed before it can be sent, and the checks say how many days ahead it must be.
originalReleaseDatestring (date): For music that came out before: the day it first did.
copyrightobject: Left out of a new release, the label's release defaults fill in the holders, with this year.
copyright.cLineobject: The © line: the rights in the artwork and text.
copyright.cLine.yearinteger: From 1900 to 2200.
copyright.cLine.holderstring: Who holds the rights, such as the label's name. Up to 180 characters.
copyright.pLineobject: The ℗ line: the rights in the recordings.
copyright.pLine.yearinteger: From 1900 to 2200.
copyright.pLine.holderstring: Who holds the rights, such as the label's name. Up to 180 characters.
territoriesobject: Where the release may be sold; new releases are WORLDWIDE unless the label's defaults say otherwise.
territories.modestringRequired: WORLDWIDE, or CUSTOM to license only the listed countries. One of WORLDWIDE, CUSTOM.
territories.codesstring[]: Two-letter country codes, for CUSTOM. Up to 300 items.
storesobject: Which stores get the release; new releases go to ALL.
stores.modestringRequired: ALL stores (new ones included), or CUSTOM to deliver only to the listed ones. One of ALL, CUSTOM.
stores.codesstring[]: Store codes from GET /v1/reference, for CUSTOM. Each one of spotify, apple_music, amazon_music, youtube_music, deezer, tidal, pandora, soundcloud, audiomack, napster, qobuz, iheartradio, youtube_content_id, tiktok, meta, snapchat, triller, beatport, traxsource, juno_download, 7digital, tencent, netease, jiosaavn, gaana, hungama, joox, kkbox, line_music, awa, melon, genie, flo, bugs, vibe, anghami, boomplay, mdundo, yandex_music, vk_music, zvuk, fizy, claro_musica, peloton, trebel, shazam, gracenote, audible_magic. Up to 200 items. Default [].
upcstring: Your own UPC or EAN, when the release already has one; otherwise one is assigned on delivery (release.codes_assigned).
externalIdstring: Your own identifier for this record, unique within the organization. 1 to 100 characters.
metadatamap of string: Key-value pairs you attach for your own use.
tracksobject[]: Tracks to create with the release, in order. Up to 100 items.
tracks[].titlestringRequired: 1 to 180 characters.
tracks[].versionTitlestring: Up to 120 characters.
tracks[].primaryArtistIdsstring[]: Up to 20 items.
tracks[].featuredArtistIdsstring[]: Up to 20 items.
tracks[].explicitboolean: Explicit lyrics or content; new releases and tracks start with false.
tracks[].isCoverboolean: Someone else's song: it needs a cover licence before delivery.
tracks[].languagestring: An ISO 639-1 code ("en") or a language name from GET /v1/reference.
tracks[].isrcstring: Your own ISRC, when the recording already has one; otherwise one is assigned when the release is submitted or delivered.
tracks[].lyricsstring: Up to 20000 characters.
tracks[].creditsobject: The people behind the track, as lists of names by role.
tracks[].credits.songwritersstring[]: Up to 30 items.
tracks[].credits.composersstring[]: Up to 30 items.
tracks[].credits.producersstring[]: Up to 30 items.
tracks[].credits.publishersstring[]: Up to 30 items.
tracks[].credits.mixersstring[]: Up to 30 items.
tracks[].credits.masteringEngineersstring[]: Up to 30 items.
tracks[].credits.remixersstring[]: Up to 30 items.
tracks[].externalIdstring: Your own identifier for this record, unique within the organization. 1 to 100 characters.
tracks[].metadatamap of string: Key-value pairs you attach for your own use.

Headers#

Idempotency-Key: Any unique value, such as a UUID: a retry with the same key and body gets the first answer again for 24 hours.
Stillmore-Organization: A sub-label to act for, when the key may (see Sub-labels).

Example request#

curl -X POST "https://api.stillmoregroup.com/api/v1/releases" \
  -H "Authorization: Bearer $STILLMORE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Night Signals",
    "type": "SINGLE",
    "primaryArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "primaryGenre": "Pop",
    "language": "en",
    "explicit": false,
    "releaseDate": "2027-01-15",
    "tracks": [
      {
        "title": "Night Signals",
        "explicit": false,
        "language": "en",
        "isrc": "GBXYZ2600001"
      }
    ]
  }'

Response 201#

data holds the object below.

idstring
labelIdstring
titlestring
versionTitlestring or null
typestring: One of SINGLE, EP, ALBUM.
statusstring: Where the release is, review and delivery together. One of DRAFT, LABEL_REVIEW, IN_REVIEW, CHANGES_REQUESTED, REJECTED, APPROVED, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN, ARCHIVED.
primaryArtistIdsstring[]
featuredArtistIdsstring[]

Show 66 more fields

primaryGenrestring or null
secondaryGenrestring or null
languagestring or null
explicitboolean
releaseDatestring (date) or null
originalReleaseDatestring (date) or null
copyrightobject
copyright.cLineobject
copyright.pLineobject
territoriesobject
territories.modestring: One of WORLDWIDE, CUSTOM.
territories.codesstring[]
storesobject
stores.modestring: One of ALL, CUSTOM.
stores.codesstring[]
upcstring or null
artworkobject or null: The cover; null until one is uploaded.
artwork.statusstring: One of PENDING_UPLOAD, UPLOADED, VERIFIED, FAILED, DELETED.
artwork.fileNamestring or null
artwork.mimeTypestring or null
artwork.sizeBytesnumber or null
artwork.uploadedAtstring or null: ISO 8601 timestamp in UTC.
artwork.widthnumber or null
artwork.heightnumber or null
trackCountinteger: From -9007199254740991 to 9007199254740991.
tracksobject[]: Included when one release is read, created or changed.
tracks[].idstring
tracks[].releaseIdstring
tracks[].positioninteger: From -9007199254740991 to 9007199254740991.
tracks[].titlestring
tracks[].versionTitlestring or null
tracks[].primaryArtistIdsstring[]
tracks[].featuredArtistIdsstring[]
tracks[].explicitboolean
tracks[].isCoverboolean
tracks[].languagestring or null
tracks[].isrcstring or null
tracks[].lyricsstring or null
tracks[].creditsobject
tracks[].audioobject or null: The master; null until one is uploaded.
tracks[].externalIdstring or null: Your own id for it, when you set one.
tracks[].metadatamap of string: Your own keys and values, as you sent them.
tracks[].createdAtstring: ISO 8601 timestamp in UTC.
tracks[].updatedAtstring: ISO 8601 timestamp in UTC.
tracks[].revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.
reviewobject: Included when one release is read, created or changed.
review.submittedAtstring or null: ISO 8601 timestamp in UTC.
review.decidedAtstring or null: ISO 8601 timestamp in UTC.
review.automaticboolean: The account's automatic approval passed the release without a person.
review.notestring or null: What review asked for when it sent the release back, or why it rejected it.
review.issuesobject[]
review.documentsRequestedobject or null
deliveryobject: On its way to the stores, codes and store pages; included when one release is read, created or changed.
delivery.statusstring: One of NOT_SENT, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN.
delivery.sentAtstring or null
delivery.liveAtstring or null
delivery.refusedReasonstring or null
delivery.storeLinksobject[]
delivery.smartLinkobject or null
submittedAtstring or null: ISO 8601 timestamp in UTC.
approvedAtstring or null: ISO 8601 timestamp in UTC.
externalIdstring or null: Your own id for it, when you set one.
metadatamap of string: Your own keys and values, as you sent them.
createdAtstring: ISO 8601 timestamp in UTC.
updatedAtstring: ISO 8601 timestamp in UTC.
revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.

Example response

{
  "data": {
    "id": "6731c2a1b3c4d5e6f7a8b9c0",
    "labelId": "6731c2a1b3c4d5e6f7a8b9c0",
    "title": "Night Signals",
    "versionTitle": "Radio Edit",
    "type": "SINGLE",
    "status": "DRAFT",
    "primaryArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "featuredArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "primaryGenre": "Pop",
    "secondaryGenre": "Pop",
    "language": "en",
    "explicit": false,
    "releaseDate": "2027-01-15",
    "originalReleaseDate": "2026-10-01",
    "copyright": {
      "cLine": {
        "year": 2026,
        "holder": "North Records"
      },
      "pLine": {
        "year": 2026,
        "holder": "North Records"
      }
    },
    "territories": {
      "mode": "WORLDWIDE",
      "codes": [
        "123456"
      ]
    },
    "stores": {
      "mode": "ALL",
      "codes": [
        "123456"
      ]
    },
    "upc": "0612345678905",
    "artwork": {
      "status": "PENDING_UPLOAD",
      "fileName": "cover.jpg",
      "mimeType": "…",
      "sizeBytes": 2483117,
      "uploadedAt": "2026-11-01T09:30:00.000Z",
      "width": 1,
      "height": 1
    },
    "trackCount": 1200,
    "tracks": [
      {
        "id": "6731c2a1b3c4d5e6f7a8b9c0",
        "releaseId": "6731c2a1b3c4d5e6f7a8b9c0",
        "position": 1,
        "title": "Night Signals",
        "versionTitle": "Radio Edit",
        "primaryArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "featuredArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "explicit": false,
        "isCover": false,
        "language": "en",
        "isrc": "GBXYZ2600001",
        "lyrics": "…",
        "credits": {
          "songwriters": [],
          "composers": [],
          "producers": [],
          "publishers": [],
          "mixers": [],
          "masteringEngineers": [],
          "remixers": []
        },
        "audio": {
          "status": "PENDING_UPLOAD",
          "fileName": "cover.jpg",
          "mimeType": "…",
          "sizeBytes": 2483117,
          "uploadedAt": "2026-11-01T09:30:00.000Z",
          "durationSeconds": 214,
          "sampleRate": 1,
          "bitDepth": 1,
          "channels": 1
        },
        "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
        "metadata": {
          "catalogueId": "1042"
        },
        "createdAt": "2026-11-01T09:30:00.000Z",
        "updatedAt": "2026-11-01T09:30:00.000Z",
        "revision": "…"
      }
    ],
    "review": {
      "submittedAt": "2026-11-01T09:30:00.000Z",
      "decidedAt": "2026-11-01T09:30:00.000Z",
      "automatic": false,
      "note": "Sent from our catalogue system",
      "issues": [
        {
          "category": "…",
          "message": "Sent from our catalogue system"
        }
      ],
      "documentsRequested": {
        "note": "Sent from our catalogue system",
        "requestedAt": "2026-11-01T09:30:00.000Z",
        "fulfilled": false
      }
    },
    "delivery": {
      "status": "NOT_SENT",
      "sentAt": "2026-11-01T09:30:00.000Z",
      "liveAt": "2026-11-01T09:30:00.000Z",
      "refusedReason": "Sent from our catalogue system",
      "storeLinks": [
        {
          "store": "Spotify",
          "url": "https://example.com/webhooks/stillmore"
        }
      ],
      "smartLink": {
        "url": "https://example.com/webhooks/stillmore",
        "enabled": true
      }
    },
    "submittedAt": "2026-11-01T09:30:00.000Z",
    "approvedAt": "2026-11-01T09:30:00.000Z",
    "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
    "metadata": {
      "catalogueId": "1042"
    },
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z",
    "revision": "…"
  }
}

Errors#

Code	What it means
`EXTERNAL_ID_IN_USE`	Another record of the same kind in your organization already has this externalId.
`UPC_IN_USE`	Another release already carries this UPC.
`LABEL_NOT_FOUND`	From the workspace rule behind this endpoint; `message` says what to change.
`ARTIST_NOT_FOUND`	From the workspace rule behind this endpoint; `message` says what to change.
`LABEL_TRACK_LIMIT_REACHED`	From the workspace rule behind this endpoint; `message` says what to change.

Every endpoint can also give the errors every call can give, such as VALIDATION_ERROR, INSUFFICIENT_SCOPE and RATE_LIMITED.

Read a release with its tracks#

GET /releases/{releaseId} · scope releases:read

Path parameters#

releaseIdstring: An id.

Headers#

Stillmore-Organization: A sub-label to act for, when the key may (see Sub-labels).

Example request#

curl "https://api.stillmoregroup.com/api/v1/releases/{releaseId}" \
  -H "Authorization: Bearer $STILLMORE_API_KEY"

Response 200#

data holds the object below.

idstring
labelIdstring
titlestring
versionTitlestring or null
typestring: One of SINGLE, EP, ALBUM.
statusstring: Where the release is, review and delivery together. One of DRAFT, LABEL_REVIEW, IN_REVIEW, CHANGES_REQUESTED, REJECTED, APPROVED, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN, ARCHIVED.
primaryArtistIdsstring[]
featuredArtistIdsstring[]

Show 66 more fields

primaryGenrestring or null
secondaryGenrestring or null
languagestring or null
explicitboolean
releaseDatestring (date) or null
originalReleaseDatestring (date) or null
copyrightobject
copyright.cLineobject
copyright.pLineobject
territoriesobject
territories.modestring: One of WORLDWIDE, CUSTOM.
territories.codesstring[]
storesobject
stores.modestring: One of ALL, CUSTOM.
stores.codesstring[]
upcstring or null
artworkobject or null: The cover; null until one is uploaded.
artwork.statusstring: One of PENDING_UPLOAD, UPLOADED, VERIFIED, FAILED, DELETED.
artwork.fileNamestring or null
artwork.mimeTypestring or null
artwork.sizeBytesnumber or null
artwork.uploadedAtstring or null: ISO 8601 timestamp in UTC.
artwork.widthnumber or null
artwork.heightnumber or null
trackCountinteger: From -9007199254740991 to 9007199254740991.
tracksobject[]: Included when one release is read, created or changed.
tracks[].idstring
tracks[].releaseIdstring
tracks[].positioninteger: From -9007199254740991 to 9007199254740991.
tracks[].titlestring
tracks[].versionTitlestring or null
tracks[].primaryArtistIdsstring[]
tracks[].featuredArtistIdsstring[]
tracks[].explicitboolean
tracks[].isCoverboolean
tracks[].languagestring or null
tracks[].isrcstring or null
tracks[].lyricsstring or null
tracks[].creditsobject
tracks[].audioobject or null: The master; null until one is uploaded.
tracks[].externalIdstring or null: Your own id for it, when you set one.
tracks[].metadatamap of string: Your own keys and values, as you sent them.
tracks[].createdAtstring: ISO 8601 timestamp in UTC.
tracks[].updatedAtstring: ISO 8601 timestamp in UTC.
tracks[].revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.
reviewobject: Included when one release is read, created or changed.
review.submittedAtstring or null: ISO 8601 timestamp in UTC.
review.decidedAtstring or null: ISO 8601 timestamp in UTC.
review.automaticboolean: The account's automatic approval passed the release without a person.
review.notestring or null: What review asked for when it sent the release back, or why it rejected it.
review.issuesobject[]
review.documentsRequestedobject or null
deliveryobject: On its way to the stores, codes and store pages; included when one release is read, created or changed.
delivery.statusstring: One of NOT_SENT, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN.
delivery.sentAtstring or null
delivery.liveAtstring or null
delivery.refusedReasonstring or null
delivery.storeLinksobject[]
delivery.smartLinkobject or null
submittedAtstring or null: ISO 8601 timestamp in UTC.
approvedAtstring or null: ISO 8601 timestamp in UTC.
externalIdstring or null: Your own id for it, when you set one.
metadatamap of string: Your own keys and values, as you sent them.
createdAtstring: ISO 8601 timestamp in UTC.
updatedAtstring: ISO 8601 timestamp in UTC.
revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.

Example response

{
  "data": {
    "id": "6731c2a1b3c4d5e6f7a8b9c0",
    "labelId": "6731c2a1b3c4d5e6f7a8b9c0",
    "title": "Night Signals",
    "versionTitle": "Radio Edit",
    "type": "SINGLE",
    "status": "DRAFT",
    "primaryArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "featuredArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "primaryGenre": "Pop",
    "secondaryGenre": "Pop",
    "language": "en",
    "explicit": false,
    "releaseDate": "2027-01-15",
    "originalReleaseDate": "2026-10-01",
    "copyright": {
      "cLine": {
        "year": 2026,
        "holder": "North Records"
      },
      "pLine": {
        "year": 2026,
        "holder": "North Records"
      }
    },
    "territories": {
      "mode": "WORLDWIDE",
      "codes": [
        "123456"
      ]
    },
    "stores": {
      "mode": "ALL",
      "codes": [
        "123456"
      ]
    },
    "upc": "0612345678905",
    "artwork": {
      "status": "PENDING_UPLOAD",
      "fileName": "cover.jpg",
      "mimeType": "…",
      "sizeBytes": 2483117,
      "uploadedAt": "2026-11-01T09:30:00.000Z",
      "width": 1,
      "height": 1
    },
    "trackCount": 1200,
    "tracks": [
      {
        "id": "6731c2a1b3c4d5e6f7a8b9c0",
        "releaseId": "6731c2a1b3c4d5e6f7a8b9c0",
        "position": 1,
        "title": "Night Signals",
        "versionTitle": "Radio Edit",
        "primaryArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "featuredArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "explicit": false,
        "isCover": false,
        "language": "en",
        "isrc": "GBXYZ2600001",
        "lyrics": "…",
        "credits": {
          "songwriters": [],
          "composers": [],
          "producers": [],
          "publishers": [],
          "mixers": [],
          "masteringEngineers": [],
          "remixers": []
        },
        "audio": {
          "status": "PENDING_UPLOAD",
          "fileName": "cover.jpg",
          "mimeType": "…",
          "sizeBytes": 2483117,
          "uploadedAt": "2026-11-01T09:30:00.000Z",
          "durationSeconds": 214,
          "sampleRate": 1,
          "bitDepth": 1,
          "channels": 1
        },
        "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
        "metadata": {
          "catalogueId": "1042"
        },
        "createdAt": "2026-11-01T09:30:00.000Z",
        "updatedAt": "2026-11-01T09:30:00.000Z",
        "revision": "…"
      }
    ],
    "review": {
      "submittedAt": "2026-11-01T09:30:00.000Z",
      "decidedAt": "2026-11-01T09:30:00.000Z",
      "automatic": false,
      "note": "Sent from our catalogue system",
      "issues": [
        {
          "category": "…",
          "message": "Sent from our catalogue system"
        }
      ],
      "documentsRequested": {
        "note": "Sent from our catalogue system",
        "requestedAt": "2026-11-01T09:30:00.000Z",
        "fulfilled": false
      }
    },
    "delivery": {
      "status": "NOT_SENT",
      "sentAt": "2026-11-01T09:30:00.000Z",
      "liveAt": "2026-11-01T09:30:00.000Z",
      "refusedReason": "Sent from our catalogue system",
      "storeLinks": [
        {
          "store": "Spotify",
          "url": "https://example.com/webhooks/stillmore"
        }
      ],
      "smartLink": {
        "url": "https://example.com/webhooks/stillmore",
        "enabled": true
      }
    },
    "submittedAt": "2026-11-01T09:30:00.000Z",
    "approvedAt": "2026-11-01T09:30:00.000Z",
    "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
    "metadata": {
      "catalogueId": "1042"
    },
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z",
    "revision": "…"
  }
}

Errors#

Code	What it means
`RELEASE_NOT_FOUND`	From the workspace rule behind this endpoint; `message` says what to change.

Every endpoint can also give the errors every call can give, such as VALIDATION_ERROR, INSUFFICIENT_SCOPE and RATE_LIMITED.

Change a draft release#

PATCH /releases/{releaseId} · scope releases:write

Only drafts and releases sent back for changes can change. null clears a field that can be empty.

Path parameters#

releaseIdstring: An id.

Body#

labelIdstring: The organization's own label when left out. An id.
titlestring: 1 to 180 characters.
versionTitlestring or null: Up to 120 characters.
typestring: SINGLE by default. One of SINGLE, EP, ALBUM.
primaryArtistIdsstring[]: 1 to 20 items.
featuredArtistIdsstring[]: Up to 20 items.
primaryGenrestring: A genre name from GET /v1/reference.
secondaryGenrestring: A genre name from GET /v1/reference.
languagestring: An ISO 639-1 code ("en") or a language name from GET /v1/reference.
explicitboolean: Explicit lyrics or content; new releases and tracks start with false.
releaseDatestring (date): The day it goes live in the stores; needed before it can be sent, and the checks say how many days ahead it must be.
originalReleaseDatestring (date) or null: For music that came out before: the day it first did.
copyrightobject: Left out of a new release, the label's release defaults fill in the holders, with this year.
copyright.cLineobject: The © line: the rights in the artwork and text.
copyright.cLine.yearinteger: From 1900 to 2200.
copyright.cLine.holderstring: Who holds the rights, such as the label's name. Up to 180 characters.
copyright.pLineobject: The ℗ line: the rights in the recordings.
copyright.pLine.yearinteger: From 1900 to 2200.
copyright.pLine.holderstring: Who holds the rights, such as the label's name. Up to 180 characters.
territoriesobject: Where the release may be sold; new releases are WORLDWIDE unless the label's defaults say otherwise.
territories.modestringRequired: WORLDWIDE, or CUSTOM to license only the listed countries. One of WORLDWIDE, CUSTOM.
territories.codesstring[]: Two-letter country codes, for CUSTOM. Up to 300 items.
storesobject: Which stores get the release; new releases go to ALL.
stores.modestringRequired: ALL stores (new ones included), or CUSTOM to deliver only to the listed ones. One of ALL, CUSTOM.
stores.codesstring[]: Store codes from GET /v1/reference, for CUSTOM. Each one of spotify, apple_music, amazon_music, youtube_music, deezer, tidal, pandora, soundcloud, audiomack, napster, qobuz, iheartradio, youtube_content_id, tiktok, meta, snapchat, triller, beatport, traxsource, juno_download, 7digital, tencent, netease, jiosaavn, gaana, hungama, joox, kkbox, line_music, awa, melon, genie, flo, bugs, vibe, anghami, boomplay, mdundo, yandex_music, vk_music, zvuk, fizy, claro_musica, peloton, trebel, shazam, gracenote, audible_magic. Up to 200 items. Default [].
upcstring or null: Your own UPC or EAN, when the release already has one; otherwise one is assigned on delivery (release.codes_assigned).
externalIdstring or null: Your own identifier for this record, unique within the organization. 1 to 100 characters.
metadatamap of string: Key-value pairs you attach for your own use.

Headers#

Idempotency-Key: Any unique value, such as a UUID: a retry with the same key and body gets the first answer again for 24 hours.
If-Match: The revision you read; when the object changed since, the answer is 412 REVISION_MISMATCH.
Stillmore-Organization: A sub-label to act for, when the key may (see Sub-labels).

Example request#

curl -X PATCH "https://api.stillmoregroup.com/api/v1/releases/{releaseId}" \
  -H "Authorization: Bearer $STILLMORE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SINGLE",
    "primaryGenre": "Pop",
    "language": "en",
    "explicit": false,
    "releaseDate": "2027-01-15"
  }'

Response 200#

data holds the object below.

idstring
labelIdstring
titlestring
versionTitlestring or null
typestring: One of SINGLE, EP, ALBUM.
statusstring: Where the release is, review and delivery together. One of DRAFT, LABEL_REVIEW, IN_REVIEW, CHANGES_REQUESTED, REJECTED, APPROVED, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN, ARCHIVED.
primaryArtistIdsstring[]
featuredArtistIdsstring[]

Show 66 more fields

primaryGenrestring or null
secondaryGenrestring or null
languagestring or null
explicitboolean
releaseDatestring (date) or null
originalReleaseDatestring (date) or null
copyrightobject
copyright.cLineobject
copyright.pLineobject
territoriesobject
territories.modestring: One of WORLDWIDE, CUSTOM.
territories.codesstring[]
storesobject
stores.modestring: One of ALL, CUSTOM.
stores.codesstring[]
upcstring or null
artworkobject or null: The cover; null until one is uploaded.
artwork.statusstring: One of PENDING_UPLOAD, UPLOADED, VERIFIED, FAILED, DELETED.
artwork.fileNamestring or null
artwork.mimeTypestring or null
artwork.sizeBytesnumber or null
artwork.uploadedAtstring or null: ISO 8601 timestamp in UTC.
artwork.widthnumber or null
artwork.heightnumber or null
trackCountinteger: From -9007199254740991 to 9007199254740991.
tracksobject[]: Included when one release is read, created or changed.
tracks[].idstring
tracks[].releaseIdstring
tracks[].positioninteger: From -9007199254740991 to 9007199254740991.
tracks[].titlestring
tracks[].versionTitlestring or null
tracks[].primaryArtistIdsstring[]
tracks[].featuredArtistIdsstring[]
tracks[].explicitboolean
tracks[].isCoverboolean
tracks[].languagestring or null
tracks[].isrcstring or null
tracks[].lyricsstring or null
tracks[].creditsobject
tracks[].audioobject or null: The master; null until one is uploaded.
tracks[].externalIdstring or null: Your own id for it, when you set one.
tracks[].metadatamap of string: Your own keys and values, as you sent them.
tracks[].createdAtstring: ISO 8601 timestamp in UTC.
tracks[].updatedAtstring: ISO 8601 timestamp in UTC.
tracks[].revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.
reviewobject: Included when one release is read, created or changed.
review.submittedAtstring or null: ISO 8601 timestamp in UTC.
review.decidedAtstring or null: ISO 8601 timestamp in UTC.
review.automaticboolean: The account's automatic approval passed the release without a person.
review.notestring or null: What review asked for when it sent the release back, or why it rejected it.
review.issuesobject[]
review.documentsRequestedobject or null
deliveryobject: On its way to the stores, codes and store pages; included when one release is read, created or changed.
delivery.statusstring: One of NOT_SENT, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN.
delivery.sentAtstring or null
delivery.liveAtstring or null
delivery.refusedReasonstring or null
delivery.storeLinksobject[]
delivery.smartLinkobject or null
submittedAtstring or null: ISO 8601 timestamp in UTC.
approvedAtstring or null: ISO 8601 timestamp in UTC.
externalIdstring or null: Your own id for it, when you set one.
metadatamap of string: Your own keys and values, as you sent them.
createdAtstring: ISO 8601 timestamp in UTC.
updatedAtstring: ISO 8601 timestamp in UTC.
revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.

Example response

{
  "data": {
    "id": "6731c2a1b3c4d5e6f7a8b9c0",
    "labelId": "6731c2a1b3c4d5e6f7a8b9c0",
    "title": "Night Signals",
    "versionTitle": "Radio Edit",
    "type": "SINGLE",
    "status": "DRAFT",
    "primaryArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "featuredArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "primaryGenre": "Pop",
    "secondaryGenre": "Pop",
    "language": "en",
    "explicit": false,
    "releaseDate": "2027-01-15",
    "originalReleaseDate": "2026-10-01",
    "copyright": {
      "cLine": {
        "year": 2026,
        "holder": "North Records"
      },
      "pLine": {
        "year": 2026,
        "holder": "North Records"
      }
    },
    "territories": {
      "mode": "WORLDWIDE",
      "codes": [
        "123456"
      ]
    },
    "stores": {
      "mode": "ALL",
      "codes": [
        "123456"
      ]
    },
    "upc": "0612345678905",
    "artwork": {
      "status": "PENDING_UPLOAD",
      "fileName": "cover.jpg",
      "mimeType": "…",
      "sizeBytes": 2483117,
      "uploadedAt": "2026-11-01T09:30:00.000Z",
      "width": 1,
      "height": 1
    },
    "trackCount": 1200,
    "tracks": [
      {
        "id": "6731c2a1b3c4d5e6f7a8b9c0",
        "releaseId": "6731c2a1b3c4d5e6f7a8b9c0",
        "position": 1,
        "title": "Night Signals",
        "versionTitle": "Radio Edit",
        "primaryArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "featuredArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "explicit": false,
        "isCover": false,
        "language": "en",
        "isrc": "GBXYZ2600001",
        "lyrics": "…",
        "credits": {
          "songwriters": [],
          "composers": [],
          "producers": [],
          "publishers": [],
          "mixers": [],
          "masteringEngineers": [],
          "remixers": []
        },
        "audio": {
          "status": "PENDING_UPLOAD",
          "fileName": "cover.jpg",
          "mimeType": "…",
          "sizeBytes": 2483117,
          "uploadedAt": "2026-11-01T09:30:00.000Z",
          "durationSeconds": 214,
          "sampleRate": 1,
          "bitDepth": 1,
          "channels": 1
        },
        "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
        "metadata": {
          "catalogueId": "1042"
        },
        "createdAt": "2026-11-01T09:30:00.000Z",
        "updatedAt": "2026-11-01T09:30:00.000Z",
        "revision": "…"
      }
    ],
    "review": {
      "submittedAt": "2026-11-01T09:30:00.000Z",
      "decidedAt": "2026-11-01T09:30:00.000Z",
      "automatic": false,
      "note": "Sent from our catalogue system",
      "issues": [
        {
          "category": "…",
          "message": "Sent from our catalogue system"
        }
      ],
      "documentsRequested": {
        "note": "Sent from our catalogue system",
        "requestedAt": "2026-11-01T09:30:00.000Z",
        "fulfilled": false
      }
    },
    "delivery": {
      "status": "NOT_SENT",
      "sentAt": "2026-11-01T09:30:00.000Z",
      "liveAt": "2026-11-01T09:30:00.000Z",
      "refusedReason": "Sent from our catalogue system",
      "storeLinks": [
        {
          "store": "Spotify",
          "url": "https://example.com/webhooks/stillmore"
        }
      ],
      "smartLink": {
        "url": "https://example.com/webhooks/stillmore",
        "enabled": true
      }
    },
    "submittedAt": "2026-11-01T09:30:00.000Z",
    "approvedAt": "2026-11-01T09:30:00.000Z",
    "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
    "metadata": {
      "catalogueId": "1042"
    },
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z",
    "revision": "…"
  }
}

Errors#

Code	What it means
`RELEASE_NOT_FOUND`	From the workspace rule behind this endpoint; `message` says what to change.
`RELEASE_NOT_EDITABLE`	From the workspace rule behind this endpoint; `message` says what to change.
`REVISION_MISMATCH`	The record changed since you read it (If-Match). Read it again and retry.
`UPC_IN_USE`	Another release already carries this UPC.

Every endpoint can also give the errors every call can give, such as VALIDATION_ERROR, INSUFFICIENT_SCOPE and RATE_LIMITED.

Archive a draft release#

DELETE /releases/{releaseId} · scope releases:write

Drafts and releases sent back for changes are archived (status ARCHIVED); nothing that went to review is deleted.

Path parameters#

releaseIdstring: An id.

Headers#

Stillmore-Organization: A sub-label to act for, when the key may (see Sub-labels).

Example request#

curl -X DELETE "https://api.stillmoregroup.com/api/v1/releases/{releaseId}" \
  -H "Authorization: Bearer $STILLMORE_API_KEY"

Response 200#

data holds the object below.

idstring
labelIdstring
titlestring
versionTitlestring or null
typestring: One of SINGLE, EP, ALBUM.
statusstring: Where the release is, review and delivery together. One of DRAFT, LABEL_REVIEW, IN_REVIEW, CHANGES_REQUESTED, REJECTED, APPROVED, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN, ARCHIVED.
primaryArtistIdsstring[]
featuredArtistIdsstring[]

Show 66 more fields

primaryGenrestring or null
secondaryGenrestring or null
languagestring or null
explicitboolean
releaseDatestring (date) or null
originalReleaseDatestring (date) or null
copyrightobject
copyright.cLineobject
copyright.pLineobject
territoriesobject
territories.modestring: One of WORLDWIDE, CUSTOM.
territories.codesstring[]
storesobject
stores.modestring: One of ALL, CUSTOM.
stores.codesstring[]
upcstring or null
artworkobject or null: The cover; null until one is uploaded.
artwork.statusstring: One of PENDING_UPLOAD, UPLOADED, VERIFIED, FAILED, DELETED.
artwork.fileNamestring or null
artwork.mimeTypestring or null
artwork.sizeBytesnumber or null
artwork.uploadedAtstring or null: ISO 8601 timestamp in UTC.
artwork.widthnumber or null
artwork.heightnumber or null
trackCountinteger: From -9007199254740991 to 9007199254740991.
tracksobject[]: Included when one release is read, created or changed.
tracks[].idstring
tracks[].releaseIdstring
tracks[].positioninteger: From -9007199254740991 to 9007199254740991.
tracks[].titlestring
tracks[].versionTitlestring or null
tracks[].primaryArtistIdsstring[]
tracks[].featuredArtistIdsstring[]
tracks[].explicitboolean
tracks[].isCoverboolean
tracks[].languagestring or null
tracks[].isrcstring or null
tracks[].lyricsstring or null
tracks[].creditsobject
tracks[].audioobject or null: The master; null until one is uploaded.
tracks[].externalIdstring or null: Your own id for it, when you set one.
tracks[].metadatamap of string: Your own keys and values, as you sent them.
tracks[].createdAtstring: ISO 8601 timestamp in UTC.
tracks[].updatedAtstring: ISO 8601 timestamp in UTC.
tracks[].revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.
reviewobject: Included when one release is read, created or changed.
review.submittedAtstring or null: ISO 8601 timestamp in UTC.
review.decidedAtstring or null: ISO 8601 timestamp in UTC.
review.automaticboolean: The account's automatic approval passed the release without a person.
review.notestring or null: What review asked for when it sent the release back, or why it rejected it.
review.issuesobject[]
review.documentsRequestedobject or null
deliveryobject: On its way to the stores, codes and store pages; included when one release is read, created or changed.
delivery.statusstring: One of NOT_SENT, SENT_TO_STORES, LIVE, REFUSED_BY_STORES, TAKEDOWN_REQUESTED, TAKEN_DOWN.
delivery.sentAtstring or null
delivery.liveAtstring or null
delivery.refusedReasonstring or null
delivery.storeLinksobject[]
delivery.smartLinkobject or null
submittedAtstring or null: ISO 8601 timestamp in UTC.
approvedAtstring or null: ISO 8601 timestamp in UTC.
externalIdstring or null: Your own id for it, when you set one.
metadatamap of string: Your own keys and values, as you sent them.
createdAtstring: ISO 8601 timestamp in UTC.
updatedAtstring: ISO 8601 timestamp in UTC.
revisionstring: Changes whenever the record does; send it back in If-Match to refuse an update when someone else changed it first.

Example response

{
  "data": {
    "id": "6731c2a1b3c4d5e6f7a8b9c0",
    "labelId": "6731c2a1b3c4d5e6f7a8b9c0",
    "title": "Night Signals",
    "versionTitle": "Radio Edit",
    "type": "SINGLE",
    "status": "DRAFT",
    "primaryArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "featuredArtistIds": [
      "6731c2a1b3c4d5e6f7a8b9c0"
    ],
    "primaryGenre": "Pop",
    "secondaryGenre": "Pop",
    "language": "en",
    "explicit": false,
    "releaseDate": "2027-01-15",
    "originalReleaseDate": "2026-10-01",
    "copyright": {
      "cLine": {
        "year": 2026,
        "holder": "North Records"
      },
      "pLine": {
        "year": 2026,
        "holder": "North Records"
      }
    },
    "territories": {
      "mode": "WORLDWIDE",
      "codes": [
        "123456"
      ]
    },
    "stores": {
      "mode": "ALL",
      "codes": [
        "123456"
      ]
    },
    "upc": "0612345678905",
    "artwork": {
      "status": "PENDING_UPLOAD",
      "fileName": "cover.jpg",
      "mimeType": "…",
      "sizeBytes": 2483117,
      "uploadedAt": "2026-11-01T09:30:00.000Z",
      "width": 1,
      "height": 1
    },
    "trackCount": 1200,
    "tracks": [
      {
        "id": "6731c2a1b3c4d5e6f7a8b9c0",
        "releaseId": "6731c2a1b3c4d5e6f7a8b9c0",
        "position": 1,
        "title": "Night Signals",
        "versionTitle": "Radio Edit",
        "primaryArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "featuredArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "explicit": false,
        "isCover": false,
        "language": "en",
        "isrc": "GBXYZ2600001",
        "lyrics": "…",
        "credits": {
          "songwriters": [],
          "composers": [],
          "producers": [],
          "publishers": [],
          "mixers": [],
          "masteringEngineers": [],
          "remixers": []
        },
        "audio": {
          "status": "PENDING_UPLOAD",
          "fileName": "cover.jpg",
          "mimeType": "…",
          "sizeBytes": 2483117,
          "uploadedAt": "2026-11-01T09:30:00.000Z",
          "durationSeconds": 214,
          "sampleRate": 1,
          "bitDepth": 1,
          "channels": 1
        },
        "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
        "metadata": {
          "catalogueId": "1042"
        },
        "createdAt": "2026-11-01T09:30:00.000Z",
        "updatedAt": "2026-11-01T09:30:00.000Z",
        "revision": "…"
      }
    ],
    "review": {
      "submittedAt": "2026-11-01T09:30:00.000Z",
      "decidedAt": "2026-11-01T09:30:00.000Z",
      "automatic": false,
      "note": "Sent from our catalogue system",
      "issues": [
        {
          "category": "…",
          "message": "Sent from our catalogue system"
        }
      ],
      "documentsRequested": {
        "note": "Sent from our catalogue system",
        "requestedAt": "2026-11-01T09:30:00.000Z",
        "fulfilled": false
      }
    },
    "delivery": {
      "status": "NOT_SENT",
      "sentAt": "2026-11-01T09:30:00.000Z",
      "liveAt": "2026-11-01T09:30:00.000Z",
      "refusedReason": "Sent from our catalogue system",
      "storeLinks": [
        {
          "store": "Spotify",
          "url": "https://example.com/webhooks/stillmore"
        }
      ],
      "smartLink": {
        "url": "https://example.com/webhooks/stillmore",
        "enabled": true
      }
    },
    "submittedAt": "2026-11-01T09:30:00.000Z",
    "approvedAt": "2026-11-01T09:30:00.000Z",
    "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
    "metadata": {
      "catalogueId": "1042"
    },
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z",
    "revision": "…"
  }
}

Errors#

Code	What it means
`RELEASE_NOT_FOUND`	From the workspace rule behind this endpoint; `message` says what to change.
`RELEASE_NOT_EDITABLE`	From the workspace rule behind this endpoint; `message` says what to change.

Every endpoint can also give the errors every call can give, such as VALIDATION_ERROR, INSUFFICIENT_SCOPE and RATE_LIMITED.

Create many draft releases#

POST /releases/batch · scope releases:write

Each release is created on its own, as POST /v1/releases would; the answer lists every result in the order sent. One failing doesn't stop the others.

Body#

releasesobject[]Required: Up to 25 drafts, each created on its own. 1 to 25 items.
releases[].labelIdstring: The organization's own label when left out. An id.
releases[].titlestringRequired: 1 to 180 characters.
releases[].versionTitlestring: Up to 120 characters.
releases[].typestring: SINGLE by default. One of SINGLE, EP, ALBUM.
releases[].primaryArtistIdsstring[]Required: 1 to 20 items.
releases[].featuredArtistIdsstring[]: Up to 20 items.
releases[].primaryGenrestring: A genre name from GET /v1/reference.
releases[].secondaryGenrestring: A genre name from GET /v1/reference.
releases[].languagestring: An ISO 639-1 code ("en") or a language name from GET /v1/reference.
releases[].explicitboolean: Explicit lyrics or content; new releases and tracks start with false.
releases[].releaseDatestring (date): The day it goes live in the stores; needed before it can be sent, and the checks say how many days ahead it must be.
releases[].originalReleaseDatestring (date): For music that came out before: the day it first did.
releases[].copyrightobject: Left out of a new release, the label's release defaults fill in the holders, with this year.
releases[].copyright.pLineobject: The ℗ line: the rights in the recordings.
releases[].territoriesobject: Where the release may be sold; new releases are WORLDWIDE unless the label's defaults say otherwise.
releases[].territories.modestringRequired: WORLDWIDE, or CUSTOM to license only the listed countries. One of WORLDWIDE, CUSTOM.
releases[].territories.codesstring[]: Two-letter country codes, for CUSTOM. Up to 300 items.
releases[].storesobject: Which stores get the release; new releases go to ALL.
releases[].stores.modestringRequired: ALL stores (new ones included), or CUSTOM to deliver only to the listed ones. One of ALL, CUSTOM.
releases[].stores.codesstring[]: Store codes from GET /v1/reference, for CUSTOM. Each one of spotify, apple_music, amazon_music, youtube_music, deezer, tidal, pandora, soundcloud, audiomack, napster, qobuz, iheartradio, youtube_content_id, tiktok, meta, snapchat, triller, beatport, traxsource, juno_download, 7digital, tencent, netease, jiosaavn, gaana, hungama, joox, kkbox, line_music, awa, melon, genie, flo, bugs, vibe, anghami, boomplay, mdundo, yandex_music, vk_music, zvuk, fizy, claro_musica, peloton, trebel, shazam, gracenote, audible_magic. Up to 200 items. Default [].
releases[].upcstring: Your own UPC or EAN, when the release already has one; otherwise one is assigned on delivery (release.codes_assigned).
releases[].externalIdstring: Your own identifier for this record, unique within the organization. 1 to 100 characters.
releases[].metadatamap of string: Key-value pairs you attach for your own use.
releases[].tracksobject[]: Tracks to create with the release, in order. Up to 100 items.
releases[].tracks[].titlestringRequired: 1 to 180 characters.
releases[].tracks[].versionTitlestring: Up to 120 characters.
releases[].tracks[].primaryArtistIdsstring[]: Up to 20 items.
releases[].tracks[].featuredArtistIdsstring[]: Up to 20 items.
releases[].tracks[].explicitboolean: Explicit lyrics or content; new releases and tracks start with false.
releases[].tracks[].isCoverboolean: Someone else's song: it needs a cover licence before delivery.
releases[].tracks[].languagestring: An ISO 639-1 code ("en") or a language name from GET /v1/reference.
releases[].tracks[].isrcstring: Your own ISRC, when the recording already has one; otherwise one is assigned when the release is submitted or delivered.
releases[].tracks[].lyricsstring: Up to 20000 characters.
releases[].tracks[].creditsobject: The people behind the track, as lists of names by role.
releases[].tracks[].externalIdstring: Your own identifier for this record, unique within the organization. 1 to 100 characters.
releases[].tracks[].metadatamap of string: Key-value pairs you attach for your own use.

Headers#

Idempotency-Key: Any unique value, such as a UUID: a retry with the same key and body gets the first answer again for 24 hours.
Stillmore-Organization: A sub-label to act for, when the key may (see Sub-labels).

Example request#

curl -X POST "https://api.stillmoregroup.com/api/v1/releases/batch" \
  -H "Authorization: Bearer $STILLMORE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "releases": [
      {
        "title": "Night Signals",
        "type": "SINGLE",
        "primaryArtistIds": [
          "6731c2a1b3c4d5e6f7a8b9c0"
        ],
        "primaryGenre": "Pop",
        "language": "en",
        "explicit": false,
        "releaseDate": "2027-01-15",
        "tracks": [
          {
            "title": "Night Signals",
            "explicit": false,
            "language": "en",
            "isrc": "GBXYZ2600001"
          }
        ]
      }
    ]
  }'

Response 200#

data holds the object below.

resultsobject[]
results[].indexinteger: From -9007199254740991 to 9007199254740991.
results[].okboolean
results[].releaseobject or null
results[].errorobject or null

Example response

{
  "data": {
    "results": [
      {
        "index": 1,
        "ok": false,
        "release": {
          "id": "6731c2a1b3c4d5e6f7a8b9c0",
          "labelId": "6731c2a1b3c4d5e6f7a8b9c0",
          "title": "Night Signals",
          "versionTitle": "Radio Edit",
          "type": "SINGLE",
          "status": "DRAFT",
          "primaryArtistIds": [],
          "featuredArtistIds": [],
          "primaryGenre": "Pop",
          "secondaryGenre": "Pop",
          "language": "en",
          "explicit": false,
          "releaseDate": "2027-01-15",
          "originalReleaseDate": "2026-10-01",
          "copyright": {},
          "territories": {},
          "stores": {},
          "upc": "0612345678905",
          "artwork": {},
          "trackCount": 1200,
          "tracks": [],
          "review": {},
          "delivery": {},
          "submittedAt": "2026-11-01T09:30:00.000Z",
          "approvedAt": "2026-11-01T09:30:00.000Z",
          "externalId": "6731c2a1b3c4d5e6f7a8b9c0",
          "metadata": {
            "catalogueId": "1042"
          },
          "createdAt": "2026-11-01T09:30:00.000Z",
          "updatedAt": "2026-11-01T09:30:00.000Z",
          "revision": "…"
        },
        "error": {
          "code": "123456",
          "message": "Sent from our catalogue system",
          "details": "…"
        }
      }
    ]
  }
}