Music Delivery quickstart

This flow is for an approved organization preparing its first Direct API or guided bulk delivery. It creates durable work without treating request completion as publication or processor completion.

Prerequisites

Before sending catalog data, the organization needs a current Partner agreement, a provisioned sender, an active write cohort and a scoped credential. A human representative completes agreement and payment-regime actions; a bearer credential cannot create either record. Validation can be exercised before mutation access is activated, but submit, upload, retry and takedown also require the server-side sender cohort. Compare the channel boundaries and agreement requirements.

Validate without writing

Call validateMusicDelivery with the business manifest. Validation is strict and write-free. Resolve every blocking issue and preserve the returned normalized manifest hash and publication-attestation binding.

curl --request POST \
  https://api.kasty.app/api/v1/music-deliveries/validate \
  --header 'Authorization: Bearer YOUR_SCOPED_CREDENTIAL' \
  --header 'Content-Type: application/json' \
  --data @manifest.json

Open the complete validated manifest here without leaving the guide:

{
  "schemaVersion": "kasty.music.delivery.v1",
  "message": {
    "id": "example_delivery_listening_001",
    "type": "NEW_RELEASE",
    "createdAt": "2026-07-16T00:00:00.000Z"
  },
  "defaults": {
    "videoUse": {
      "mode": "DISABLED"
    }
  },
  "parties": [
    {
      "ref": "example_artist_001",
      "kind": "ORGANIZATION",
      "displayName": "Example Northern Signal"
    }
  ],
  "recordings": [
    {
      "ref": "example_recording_001",
      "title": "First Light",
      "artistRefs": [
        "example_artist_001"
      ],
      "identifiers": {
        "senderRecordingId": "example_track_001"
      },
      "masterAssetRef": "example_asset_master_001"
    }
  ],
  "releases": [
    {
      "ref": "example_release_001",
      "title": "First Light",
      "type": "SINGLE",
      "primaryArtistRef": "example_artist_001",
      "coverAssetRef": "example_asset_cover_001",
      "tracks": [
        {
          "recordingRef": "example_recording_001",
          "discNumber": 1,
          "trackNumber": 1,
          "sequence": 1
        }
      ],
      "identifiers": {},
      "labelName": "Example Records",
      "releaseDate": "2026-07-16",
      "dealRefs": [
        "example_deal_001"
      ]
    }
  ],
  "assets": [
    {
      "ref": "example_asset_master_001",
      "fileName": "canary-master.wav",
      "contentType": "audio/wav",
      "sizeBytes": 176444,
      "checksumSha256": "9e7d1ee7be1fe98a6d6fa46159666e7fc49ce044d44fe3a8153bafa76a25d18a"
    },
    {
      "ref": "example_asset_cover_001",
      "fileName": "canary-cover.png",
      "contentType": "image/png",
      "sizeBytes": 20726,
      "checksumSha256": "ad8ab180c85527e603f83e4b79a13a7a1a94597415d3f7f0478d1b35ce455bc5"
    }
  ],
  "deals": [
    {
      "ref": "example_deal_001",
      "use": "LISTENING",
      "territories": [
        "WORLDWIDE"
      ],
      "startsAt": null,
      "endsAt": null,
      "recordingRefs": [
        "example_recording_001"
      ],
      "releaseRefs": [
        "example_release_001"
      ]
    }
  ]
}

See Validation for JSON paths, blocking errors and warnings.

Submit idempotently

Add the exact versioned rights declaration when the current rollout requires it, then call submitMusicDelivery. The authenticated sender plus message.id is the idempotency key. Replaying the same normalized payload and evidence returns the existing batch; reusing the key for different content conflicts.

Store the returned batch public ID. A successful response means Kasty accepted durable work, not that audio processing finished. listMusicDeliveries lists the authenticated sender's batches with cursor, status and search filters.

Upload assets

For every declared asset, call createMusicDeliveryUploadIntent. Upload the exact bytes directly to the returned object-scoped URL with the required headers, then call completeMusicDeliveryUpload.

Expired URLs renew the same logical (batch, assetRef) intent. Do not create a new asset identity. Read Assets and uploads before implementing progress UI.

Follow durable work

Poll getMusicDeliveryBatch, list item state and inspect stable issues. Upload progress, storage verification, catalog coordination and media processing are different phases. Retry only work explicitly marked retryable through retryMusicDeliveryBatch.

Continue with Jobs and retries, Issues and Rights and video use.