---
title: "Upsert a work-in-progress release snapshot"
method: POST
path: "/drafts"
---

# Upsert a work-in-progress release snapshot

`POST /drafts`

Pass release_id (or conversation_id) to update an existing draft. When neither is provided, a new draft release is created from the payload and its releaseId is returned with releaseCreated: true — reuse it on follow-up calls. Drafts do not enforce submission validation, but the response reports submittable (boolean) and submissionWarnings (array of per-field messages) so an unsubmittable draft surfaces before POST /releases.

## Request body

- DraftRequest
  - `release` ReleaseInput
    - `title` string, required
    - `title_version` string — Version qualifier (e.g. Remix, Acoustic Cover). Never the bare word "Cover" — mark covers with track_type instead.
    - `primary_artist_name` string, required
    - `primary_artists` PrimaryArtistInput[] — Every primary artist in credit order. The first entry is the main primary artist and must match primary_artist_name when both are sent; the rest are added as "Primary Artist" contributors. Each entry's profile links map that artist to their existing store profile.
      - `name` string, required
      - `spotify_artist_url` string — Spotify artist profile URL (https://open.spotify.com/artist/…). Album/song links are rejected.
      - `apple_music_artist_url` string — Apple Music artist profile URL (https://music.apple.com/<storefront>/artist/<slug>/<id>). Album/song links are rejected.
      - `soundcloud_artist_url` string
      - `meta_artist_url` string
    - `spotify_artist_urls` string[] — Positional alternative to primary_artists: entry N is the Spotify artist profile link for primary artist N. Use null to hold a position. Cannot be longer than the primary artist list.
    - `apple_music_artist_urls` string[] — Positional Apple Music artist profile links, matched to the primary artists by index.
    - `spotify_artist_url` string — Spotify artist profile URL for the main primary artist.
    - `apple_music_artist_url` string — Apple Music artist profile URL for the main primary artist.
    - `genre` string, required
    - `sub_genre` string — Optional second genre
    - `second_genre` string — Accepted alias for sub_genre
    - `release_date` string, date, required
    - `label` string — Record label name
    - `audio_language` string
    - `metadata_language` string
    - `metadata_language_country` string
    - `distribution_store_ids` integer[], nullable — New clients should send a non-empty array of supported DSP store IDs, or null for all supported stores. Omitted legacy payloads default to all supported stores.
    - `pline_year` string
    - `pline_owner` string
    - `cline_year` string
    - `cline_owner` string
    - `cover_art_file_url` string, required
    - `contributors` ContributorInput[]
      - `name` string
      - `role` string
      - `roleId` number
      - `contributorRoleGroupId` number
    - `artist_locals` ArtistLocalizationInput[]
      - `name` string
      - `language` string — ISO 639-1 code such as ko, zh, ja; resolved to the Revelator language ID at submission. Preferred over languageId.
      - `languageId` number — Revelator-internal numeric language ID; provide language instead when only the ISO code is known.
      - `phoneticName` string
  - `tracks` TrackInput[]
    - `title` string, required
    - `title_version` string — Use Remix here for remixes; track_type does not accept remix. Never the bare word "Cover" — mark covers with track_type: "cover"; a version naming the kind of cover (e.g. "Acoustic Cover") is allowed.
    - `primary_artist_name` string
    - `primary_artists` PrimaryArtistInput[] — Primary artists for this track, in credit order, when they differ from the release. Same shape and behaviour as release.primary_artists.
      - `name` string, required
      - `spotify_artist_url` string — Spotify artist profile URL (https://open.spotify.com/artist/…). Album/song links are rejected.
      - `apple_music_artist_url` string — Apple Music artist profile URL (https://music.apple.com/<storefront>/artist/<slug>/<id>). Album/song links are rejected.
      - `soundcloud_artist_url` string
      - `meta_artist_url` string
    - `audio_file_url` string, required
    - `explicit_flag` boolean, required
    - `track_type` 'original' | 'cover' | 'public_domain'
    - `isrc` string — Optional valid ISRC
    - `genre` string
    - `language` string
    - `lyrics` string — Plain-text lyrics
    - `preview_start_seconds` integer — Preview/clip start time in seconds. Where the clip starts when a listener previews the track. Defaults to 15 when omitted.
    - `pline_year` string
    - `pline_owner` string
    - `cline_year` string
    - `cline_owner` string
    - `writers` WriterInput[], required
      - `name` string, required — Full legal name
      - `society` string
      - `ipi` string
      - `share_percent` number
    - `contributors` ContributorInput[]
      - `name` string
      - `role` string
      - `roleId` number
      - `contributorRoleGroupId` number
    - `artist_locals` ArtistLocalizationInput[]
      - `name` string
      - `language` string — ISO 639-1 code such as ko, zh, ja; resolved to the Revelator language ID at submission. Preferred over languageId.
      - `languageId` number — Revelator-internal numeric language ID; provide language instead when only the ISO code is known.
      - `phoneticName` string
  - `track_patches` object[]
  - `upload_requests` object[]
  - `status` string
  - `mode` 'delta' | 'replace'
  - `release_id` string — Existing draft release to update. Omit together with conversation_id to create a new draft release.
  - `conversation_id` string — Existing chat conversation whose draft should be updated.

## Response `200`

Draft snapshot result

---

[API](https://skmtc.dev/once/apis/once-rest-api.md) · [All operations](https://skmtc.dev/once/apis/once-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/once/once-rest-api/revisions/6b7f882e04ff/schema)