ONCE Documentation

Once your assets are uploaded, you can save a draft and submit a release for distribution. All endpoints require authentication.

Read the rules first

Before building payloads, read GET /v1/metadata-rules (artist-name policy, title casing, writers, UPC, AI disclosure, cover songs) and GET /v1/release-schema (authoritative required fields and an example payload). The platform enforces these rules at submission, so reading them first saves you rejected requests.

curl https://once.app/v1/metadata-rules
curl -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" https://once.app/v1/release-schema

Drafts

curl -X POST https://once.app/v1/drafts \
  -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "release": { ... }, "tracks": [ ... ], "mode": "delta" }'

POST /v1/drafts upserts a work-in-progress release snapshot. Body: { "release"?, "tracks"?, "track_patches"?, "upload_requests"?, "status"?, "mode"?: "delta" | "replace", "release_id"?, "conversation_id"? }. Use mode: "delta" to patch an existing draft or mode: "replace" to overwrite it.

Submit a release

curl -X POST https://once.app/v1/releases \
  -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "release": { ... }, "tracks": [ ... ] }'

POST /v1/releases submits the release for distribution and returns 201. Build the body from GET /v1/release-schema, attaching the fileUrls returned by your uploads and cover-art calls. Submission debits credits from your account (1 credit per human song, 2 per AI-detected song). Releases are distributed to all supported stores.

Partners can attach the X-Once-Provenance header (e.g. AIMD) so the release is attributed to their surface.

After submission, poll release status to follow delivery.

List releases

curl -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  'https://once.app/v1/releases?limit=100'

GET /v1/releases returns recent releases for the authenticated user (limit-only paging). GET /v1/releases/:id returns the merged metadata for a single release (its draft snapshot or latest merged data).

AI Detection Status