• SongkeeperSongkeeper

Search Documentation

Search for articles and glossary terms

Articles
  • Getting Started
  • Artists
  • Contacts
  • Contract Vault
  • Files
  • Glossary
  • Ideas
  • Keyboard Shortcuts
  • Media Library
  • Playlists
  • Projects
  • Recording Versions
  • Releases
    • Export Readiness
    • Labels and Imprints
    • Publishing Status
  • Settings
  • Songs
  1. Docs
  3. releases
  5. publishing

When Published Releases Appear in the API

Draft vs Published release status, required metadata, release date gating, and how to schedule or unpublish releases in Songkeeper's external REST API.

Releases have two statuses: Draft and Published. Together with the release date, these control when your music is visible through the Songkeeper API.

Quick answer
A release appears in the external REST API only when it is Published and its release date has arrived. The Songkeeper app still shows your own releases regardless of status or release date.

Publishing Requirements

Before a release can be set to Published, it must have:

  • A title
  • A release date
  • At least one primary artist

If any of these are missing, Songkeeper will show an error when you try to publish. Tracks, UPC/EAN, artwork, label, and export metadata can still be important for your workflow, but they are checked by release details and export readiness rather than by the publish status toggle.

Release Date Gating

Setting a release to Published doesn't immediately make it visible in the API. The Songkeeper API only returns releases that are both published and past their release date.

Status and dateVisible in the app?Visible in the API?
Draft with any release dateYesNo
Published with a future release dateYesNo
Published with a release date that has arrivedYesYes
Published release switched back to DraftYesNo
Internal vs external visibility
You can always see all your releases in Songkeeper regardless of status or date. The status and date gating only applies to the external REST API used by authenticated API clients.

Typical Workflow

  1. Create a release in Draft and fill in all the metadata, tracks, and artwork.
  2. Set the release date to your planned launch day.
  3. Switch to Published when everything is finalized. The release is ready for the API date gate, but a future release date still keeps it hidden externally.
  4. On the release date, the API automatically starts returning the release.

Related docs

  • Releases explains the release model and the data stored on a release.
  • Release exports explains the metadata readiness checks that are separate from publishing status.
  • Release labels explains Record Company and Label / Imprint fields.