Music Delivery API reference

The generated reference below follows the canonical OpenAPI 3.1 contract. Read the quickstart and operational guides before enabling writes for a Partner sender.

Download OpenAPI YAML Read the quickstart

POST/validate

Validate a manifest without writing data

Requires `deliveries.validate`. This is a strict, write-free dry run. The response uses stable issue codes and JSONPath locations. When the publication-attestation rollout applies, a valid response also returns the exact public account/sender binding, normalized business-manifest SHA-256, territories, and resolved video-use scope needed to construct `rightsDeclaration`. Validation creates no acceptance evidence.

Operation ID: validateMusicDelivery
Scope: deliveries.validate
Status: Available contract

Request body

Required

application/jsonSchemaDeliveryManifestV1

Request · One recording delivered as a single

{
  "schemaVersion": "kasty.music.delivery.v1",
  "message": {
    "id": "kasty-canary-2026-0001",
    "type": "NEW_RELEASE",
    "createdAt": "2026-07-14T12:00:00.000Z"
  },
  "defaults": {
    "videoUse": {
      "mode": "DISABLED"
    }
  },
  "parties": [
    {
      "ref": "artist:kasty-canary-signal",
      "kind": "ORGANIZATION",
      "displayName": "Kasty Canary Signal"
    }
  ],
  "recordings": [
    {
      "ref": "recording:canary-signal",
      "title": "Canary Signal",
      "artistRefs": [
        "artist:kasty-canary-signal"
      ],
      "identifiers": {
        "senderRecordingId": "kasty-canary-recording"
      },
      "masterAssetRef": "asset:canary-master"
    }
  ],
  "releases": [
    {
      "ref": "release:canary-signal",
      "title": "Canary Signal",
      "type": "SINGLE",
      "primaryArtistRef": "artist:kasty-canary-signal",
      "coverAssetRef": "asset:canary-cover",
      "tracks": [
        {
          "recordingRef": "recording:canary-signal",
          "discNumber": 1,
          "trackNumber": 1,
          "sequence": 1
        }
      ],
      "identifiers": {},
      "dealRefs": [
        "deal:canary-listening-worldwide"
      ]
    }
  ],
  "assets": [
    {
      "ref": "asset:canary-master",
      "fileName": "canary-master.wav",
      "contentType": "audio/wav",
      "sizeBytes": 176444,
      "checksumSha256": "9e7d1ee7be1fe98a6d6fa46159666e7fc49ce044d44fe3a8153bafa76a25d18a"
    },
    {
      "ref": "asset:canary-cover",
      "fileName": "canary-cover.png",
      "contentType": "image/png",
      "sizeBytes": 20726,
      "checksumSha256": "ad8ab180c85527e603f83e4b79a13a7a1a94597415d3f7f0478d1b35ce455bc5"
    }
  ],
  "deals": [
    {
      "ref": "deal:canary-listening-worldwide",
      "use": "LISTENING",
      "territories": [
        "WORLDWIDE"
      ],
      "startsAt": null,
      "endsAt": null,
      "recordingRefs": [
        "recording:canary-signal"
      ],
      "releaseRefs": [
        "release:canary-signal"
      ]
    }
  ]
}

Responses

Response 200

Validation completed, including invalid manifests.

application/jsonSchemaValidationResponse

Response 200 · valid

{
  "valid": true,
  "manifestSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "itemCount": 7,
  "issues": [],
  "publicationAttestation": {
    "required": true,
    "declarationVersion": "KASTY_PARTNER_DELIVERY_RIGHTS_V1",
    "catalogAccountPublicId": "catalog_public_1",
    "senderPublicId": "sender_public_1",
    "channel": "PARTNER_API",
    "scope": {
      "releaseCount": 1,
      "recordingCount": 1,
      "assetCount": 2,
      "territories": [
        "WORLDWIDE"
      ],
      "videoUse": {
        "modes": {
          "UNDECIDED": 0,
          "DISABLED": 1,
          "FULL": 0,
          "CLIP": 0
        },
        "commercialUseRecordingCount": 0
      }
    }
  }
}

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 413

Manifest bytes or entity count exceed the credential/channel quota.

application/jsonSchemaError

Response 413 · example

{
  "code": "MUSIC_DELIVERY_MANIFEST_LIMIT_EXCEEDED",
  "message": "Delivery manifest exceeds the accepted limit"
}

Response 428

Human Partner agreement/payment state or this delivery's exact rights declaration is missing. A machine credential cannot create a human acceptance or payment acknowledgement. Follow `actionUrl` where present, then validate and submit the unchanged draft again.

application/jsonSchemaError

Response 428 · paymentAcknowledgement

{
  "code": "PARTNER_PAYMENT_ACKNOWLEDGEMENT_REQUIRED",
  "message": "Confirm the current Partner payment terms before delivering new releases",
  "currentEpoch": 3,
  "actionUrl": "https://agreements.kasty.uk/programs/KASTY_PARTNERS/payment-acknowledgement?catalogAccountId=catalog_public_1"
}

Response 428 · rightsDeclaration

{
  "code": "DELIVERY_RIGHTS_ATTESTATION_REQUIRED",
  "message": "Confirm that the represented organization controls the rights required for this delivery"
}

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

GET/

List delivery batches for the authenticated sender

Requires `deliveries.read`. Results are scoped to both the authenticated sender and catalog account, newest first.

Operation ID: listMusicDeliveries
Scope: deliveries.read
Status: Available contract

Parameters

Name	In	Required	Type	Description
`cursor`	query	No	string	Opaque cursor returned by the previous page.
`limit`	query	No	integer	—
`status`	query	No	BatchStatus	—
`search`	query	No	string	—

Responses

Response 200

One delivery batch page.

application/jsonSchemaBatchPage

Response 400

Cursor or requested page size is invalid.

application/jsonSchemaError

Response 400 · example

{
  "code": "MUSIC_DELIVERY_CURSOR_INVALID",
  "message": "Cursor or page limit is invalid"
}

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

POST/

Submit a durable delivery message

Requires `deliveries.write`. `NEW_RELEASE`, `METADATA_UPDATE`, `ASSET_UPDATE`, `DEAL_UPDATE`, and `TAKEDOWN` use this endpoint and append history; updates never overwrite prior deliveries. The pair `(authenticated sender, message.id)` is the idempotency key. Replaying the same normalized SHA-256 and complete evidence SHA-256 returns the existing batch. Different content or publication evidence with the same key returns a conflict. Partner API/bulk submission requires a declaration bound to the validation hash; the server independently resolves the current agreement acceptance, payment regime, declaration, and video-use scope in the acceptance transaction.

Operation ID: submitMusicDelivery
Scope: deliveries.write
Status: Available contract

Request body

Required

application/jsonSchemaDeliveryManifestV1

Request · One recording delivered as a single

{
  "schemaVersion": "kasty.music.delivery.v1",
  "message": {
    "id": "kasty-canary-2026-0001",
    "type": "NEW_RELEASE",
    "createdAt": "2026-07-14T12:00:00.000Z"
  },
  "defaults": {
    "videoUse": {
      "mode": "DISABLED"
    }
  },
  "parties": [
    {
      "ref": "artist:kasty-canary-signal",
      "kind": "ORGANIZATION",
      "displayName": "Kasty Canary Signal"
    }
  ],
  "recordings": [
    {
      "ref": "recording:canary-signal",
      "title": "Canary Signal",
      "artistRefs": [
        "artist:kasty-canary-signal"
      ],
      "identifiers": {
        "senderRecordingId": "kasty-canary-recording"
      },
      "masterAssetRef": "asset:canary-master"
    }
  ],
  "releases": [
    {
      "ref": "release:canary-signal",
      "title": "Canary Signal",
      "type": "SINGLE",
      "primaryArtistRef": "artist:kasty-canary-signal",
      "coverAssetRef": "asset:canary-cover",
      "tracks": [
        {
          "recordingRef": "recording:canary-signal",
          "discNumber": 1,
          "trackNumber": 1,
          "sequence": 1
        }
      ],
      "identifiers": {},
      "dealRefs": [
        "deal:canary-listening-worldwide"
      ]
    }
  ],
  "assets": [
    {
      "ref": "asset:canary-master",
      "fileName": "canary-master.wav",
      "contentType": "audio/wav",
      "sizeBytes": 176444,
      "checksumSha256": "9e7d1ee7be1fe98a6d6fa46159666e7fc49ce044d44fe3a8153bafa76a25d18a"
    },
    {
      "ref": "asset:canary-cover",
      "fileName": "canary-cover.png",
      "contentType": "image/png",
      "sizeBytes": 20726,
      "checksumSha256": "ad8ab180c85527e603f83e4b79a13a7a1a94597415d3f7f0478d1b35ce455bc5"
    }
  ],
  "deals": [
    {
      "ref": "deal:canary-listening-worldwide",
      "use": "LISTENING",
      "territories": [
        "WORLDWIDE"
      ],
      "startsAt": null,
      "endsAt": null,
      "recordingRefs": [
        "recording:canary-signal"
      ],
      "releaseRefs": [
        "release:canary-signal"
      ]
    }
  ]
}

Request · metadataUpdate

{
  "schemaVersion": "kasty.music.delivery.v1",
  "message": {
    "id": "label-2026-0002",
    "type": "METADATA_UPDATE",
    "createdAt": "2026-07-14T13:00:00.000Z"
  },
  "parties": [],
  "recordings": [],
  "releases": [],
  "assets": [],
  "deals": []
}

Request · takedown

{
  "schemaVersion": "kasty.music.delivery.v1",
  "message": {
    "id": "label-2026-0003",
    "type": "TAKEDOWN",
    "createdAt": "2026-07-14T14:00:00.000Z"
  },
  "parties": [],
  "recordings": [],
  "releases": [],
  "assets": [],
  "deals": []
}

Responses

Response 202

Delivery accepted or idempotently replayed.

application/jsonSchemaSubmitResponse

Response 202 · example

{
  "batchPublicId": "4b0588eb-2bfd-4db5-9d20-218bf131940a",
  "status": "ACCEPTED",
  "replayed": false
}

Response 400

Manifest or requested operation is invalid.

application/jsonSchemaError

Response 400 · example

{
  "code": "MUSIC_DELIVERY_MANIFEST_INVALID",
  "message": "Delivery manifest is invalid",
  "issues": [
    {
      "code": "REQUIRED",
      "severity": "BLOCKING",
      "retryable": false,
      "message": "Required value is missing",
      "suggestedAction": "Correct the manifest and validate again.",
      "entityType": "RELEASE",
      "externalRef": "release:single-42",
      "jsonPath": "$.releases[0].title",
      "fileRef": null
    }
  ]
}

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 409

Sender/message identity conflicts with prior content/evidence, or the authenticated channel is not activated for the requested delivery.

application/jsonSchemaError

Response 409 · contentChanged

{
  "code": "MUSIC_DELIVERY_IDEMPOTENCY_PAYLOAD_MISMATCH",
  "message": "This sender and message ID were already used with different content"
}

Response 409 · evidenceChanged

{
  "code": "MUSIC_DELIVERY_IDEMPOTENCY_EVIDENCE_MISMATCH",
  "message": "This sender and message ID were already used with different publication evidence"
}

Response 409 · ddexMappingMissing

{
  "code": "MUSIC_DELIVERY_DDEX_MAPPING_REQUIRED",
  "message": "DDEX delivery requires an activated sender-specific bilateral mapping"
}

Response 413

Manifest bytes or entity count exceed the credential/channel quota.

application/jsonSchemaError

Response 413 · example

{
  "code": "MUSIC_DELIVERY_MANIFEST_LIMIT_EXCEEDED",
  "message": "Delivery manifest exceeds the accepted limit"
}

Response 428

application/jsonSchemaError

Response 428 · paymentAcknowledgement

{
  "code": "PARTNER_PAYMENT_ACKNOWLEDGEMENT_REQUIRED",
  "message": "Confirm the current Partner payment terms before delivering new releases",
  "currentEpoch": 3,
  "actionUrl": "https://agreements.kasty.uk/programs/KASTY_PARTNERS/payment-acknowledgement?catalogAccountId=catalog_public_1"
}

Response 428 · rightsDeclaration

{
  "code": "DELIVERY_RIGHTS_ATTESTATION_REQUIRED",
  "message": "Confirm that the represented organization controls the rights required for this delivery"
}

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

Response 503

Partner delivery mutations are closed for this rollout stage or the authenticated sender is outside the active write cohort.

application/jsonSchemaError

Response 503 · example

{
  "code": "MUSIC_V2_PARTNER_WRITES_DISABLED",
  "message": "Partner delivery writes are not enabled for this rollout stage"
}

GET/{batchPublicId}

Read batch status and counters

Requires `deliveries.read`. Reads are scoped to both sender and catalog account.

Operation ID: getMusicDeliveryBatch
Scope: deliveries.read
Status: Available contract

Parameters

Name	In	Required	Type	Description
`batchPublicId`	path	Yes	string · uuid	—

Responses

Response 200

Current durable batch state.

application/jsonSchemaBatch

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 404

Batch does not exist in the authenticated sender/account scope.

application/jsonSchemaError

Response 404 · example

{
  "code": "MUSIC_DELIVERY_BATCH_NOT_FOUND",
  "message": "Delivery batch was not found"
}

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

GET/{batchPublicId}/items

List independently progressing delivery items

Requires `deliveries.read`. Cursor order is stable by creation time and opaque ID.

Operation ID: listMusicDeliveryItems
Scope: deliveries.read
Status: Available contract

Parameters

Name	In	Required	Type	Description
`batchPublicId`	path	Yes	string · uuid	—
`cursor`	query	No	string	Opaque cursor returned by the previous page.
`limit`	query	No	integer	—

Responses

Response 200

One item page.

application/jsonSchemaItemPage

Response 400

Cursor or requested page size is invalid.

application/jsonSchemaError

Response 400 · example

{
  "code": "MUSIC_DELIVERY_CURSOR_INVALID",
  "message": "Cursor or page limit is invalid"
}

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 404

Batch does not exist in the authenticated sender/account scope.

application/jsonSchemaError

Response 404 · example

{
  "code": "MUSIC_DELIVERY_BATCH_NOT_FOUND",
  "message": "Delivery batch was not found"
}

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

GET/{batchPublicId}/issues

List stable machine-readable issues

Requires `deliveries.read`. Blocking, retryable, and resolved state are explicit.

Operation ID: listMusicDeliveryIssues
Scope: deliveries.read
Status: Available contract

Parameters

Name	In	Required	Type	Description
`batchPublicId`	path	Yes	string · uuid	—
`cursor`	query	No	string	Opaque cursor returned by the previous page.
`limit`	query	No	integer	—

Responses

Response 200

One issue page.

application/jsonSchemaIssuePage

Response 400

Cursor or requested page size is invalid.

application/jsonSchemaError

Response 400 · example

{
  "code": "MUSIC_DELIVERY_CURSOR_INVALID",
  "message": "Cursor or page limit is invalid"
}

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 404

Batch does not exist in the authenticated sender/account scope.

application/jsonSchemaError

Response 404 · example

{
  "code": "MUSIC_DELIVERY_BATCH_NOT_FOUND",
  "message": "Delivery batch was not found"
}

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

POST/{batchPublicId}/uploads/intents

Create or renew a scoped object upload intent

Requires `assets.upload`. The server derives the object key from the authenticated account and batch; arbitrary bucket or object keys are never accepted.

Operation ID: createMusicDeliveryUploadIntent
Scope: assets.upload
Status: Available contract

Parameters

Name	In	Required	Type	Description
`batchPublicId`	path	Yes	string · uuid	—

Request body

Required

application/jsonSchemaUploadIntentRequest

Responses

Response 201

Upload intent and a short-lived object-scoped write URL.

application/jsonSchemaUploadIntent

Response 400

Manifest or requested operation is invalid.

application/jsonSchemaError

Response 400 · example

{
  "code": "MUSIC_DELIVERY_MANIFEST_INVALID",
  "message": "Delivery manifest is invalid",
  "issues": [
    {
      "code": "REQUIRED",
      "severity": "BLOCKING",
      "retryable": false,
      "message": "Required value is missing",
      "suggestedAction": "Correct the manifest and validate again.",
      "entityType": "RELEASE",
      "externalRef": "release:single-42",
      "jsonPath": "$.releases[0].title",
      "fileRef": null
    }
  ]
}

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 404

Batch does not exist in the authenticated sender/account scope.

application/jsonSchemaError

Response 404 · example

{
  "code": "MUSIC_DELIVERY_BATCH_NOT_FOUND",
  "message": "Delivery batch was not found"
}

Response 428

application/jsonSchemaError

Response 428 · paymentAcknowledgement

{
  "code": "PARTNER_PAYMENT_ACKNOWLEDGEMENT_REQUIRED",
  "message": "Confirm the current Partner payment terms before delivering new releases",
  "currentEpoch": 3,
  "actionUrl": "https://agreements.kasty.uk/programs/KASTY_PARTNERS/payment-acknowledgement?catalogAccountId=catalog_public_1"
}

Response 428 · rightsDeclaration

{
  "code": "DELIVERY_RIGHTS_ATTESTATION_REQUIRED",
  "message": "Confirm that the represented organization controls the rights required for this delivery"
}

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

Response 503

Partner delivery mutations are closed for this rollout stage or the authenticated sender is outside the active write cohort.

application/jsonSchemaError

Response 503 · example

{
  "code": "MUSIC_V2_PARTNER_WRITES_DISABLED",
  "message": "Partner delivery writes are not enabled for this rollout stage"
}

POST/{batchPublicId}/uploads/{intentPublicId}/complete

Verify and complete an uploaded asset

Requires `assets.upload`; object size, media type, and checksum are verified server-side.

Operation ID: completeMusicDeliveryUpload
Scope: assets.upload
Status: Available contract

Parameters

Name	In	Required	Type	Description
`batchPublicId`	path	Yes	string · uuid	—
`intentPublicId`	path	Yes	string · uuid	—

Responses

Response 202

Verification work accepted.

application/jsonSchemaUploadCompletion

Response 400

Manifest or requested operation is invalid.

application/jsonSchemaError

Response 400 · example

{
  "code": "MUSIC_DELIVERY_MANIFEST_INVALID",
  "message": "Delivery manifest is invalid",
  "issues": [
    {
      "code": "REQUIRED",
      "severity": "BLOCKING",
      "retryable": false,
      "message": "Required value is missing",
      "suggestedAction": "Correct the manifest and validate again.",
      "entityType": "RELEASE",
      "externalRef": "release:single-42",
      "jsonPath": "$.releases[0].title",
      "fileRef": null
    }
  ]
}

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 404

Batch does not exist in the authenticated sender/account scope.

application/jsonSchemaError

Response 404 · example

{
  "code": "MUSIC_DELIVERY_BATCH_NOT_FOUND",
  "message": "Delivery batch was not found"
}

Response 409

Catalog coordination has not reached this declared asset yet. Refresh batch/item state and retry completion with bounded backoff.

application/jsonSchemaError

Response 409 · example

{
  "code": "MUSIC_DELIVERY_CATALOG_NOT_READY",
  "message": "Catalog coordination has not reached this asset yet; retry shortly"
}

Response 410

Upload URL expired; renew the scoped intent before retrying.

application/jsonSchemaError

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

Response 503

Partner delivery mutations are closed for this rollout stage or the authenticated sender is outside the active write cohort.

application/jsonSchemaError

Response 503 · example

{
  "code": "MUSIC_V2_PARTNER_WRITES_DISABLED",
  "message": "Partner delivery writes are not enabled for this rollout stage"
}

POST/{batchPublicId}/retry

Retry retryable failed items

Requires `deliveries.write`. Permanent validation failures cannot be retried.

Operation ID: retryMusicDeliveryBatch
Scope: deliveries.write
Status: available

Parameters

Name	In	Required	Type	Description
`batchPublicId`	path	Yes	string · uuid	—

Request body

Optional

application/jsonSchemaobject

Responses

Response 202

Retryable issues were resolved and durable work was requeued.

application/jsonSchemaobject

Response 400

Manifest or requested operation is invalid.

application/jsonSchemaError

Response 400 · example

{
  "code": "MUSIC_DELIVERY_MANIFEST_INVALID",
  "message": "Delivery manifest is invalid",
  "issues": [
    {
      "code": "REQUIRED",
      "severity": "BLOCKING",
      "retryable": false,
      "message": "Required value is missing",
      "suggestedAction": "Correct the manifest and validate again.",
      "entityType": "RELEASE",
      "externalRef": "release:single-42",
      "jsonPath": "$.releases[0].title",
      "fileRef": null
    }
  ]
}

Response 401

Credential is missing, expired, revoked, or invalid.

application/jsonSchemaError

Response 401 · example

{
  "code": "MUSIC_DELIVERY_AUTH_INVALID",
  "message": "Invalid music delivery credential"
}

Response 403

Credential lacks the operation scope.

application/jsonSchemaError

Response 403 · example

{
  "code": "MUSIC_DELIVERY_SCOPE_REQUIRED",
  "message": "Credential does not grant the required scope"
}

Response 404

Batch does not exist in the authenticated sender/account scope.

application/jsonSchemaError

Response 404 · example

{
  "code": "MUSIC_DELIVERY_BATCH_NOT_FOUND",
  "message": "Delivery batch was not found"
}

Response 409

Sender/message identity conflicts with prior content/evidence, or the authenticated channel is not activated for the requested delivery.

application/jsonSchemaError

Response 409 · contentChanged

{
  "code": "MUSIC_DELIVERY_IDEMPOTENCY_PAYLOAD_MISMATCH",
  "message": "This sender and message ID were already used with different content"
}

Response 409 · evidenceChanged

{
  "code": "MUSIC_DELIVERY_IDEMPOTENCY_EVIDENCE_MISMATCH",
  "message": "This sender and message ID were already used with different publication evidence"
}

Response 409 · ddexMappingMissing

{
  "code": "MUSIC_DELIVERY_DDEX_MAPPING_REQUIRED",
  "message": "DDEX delivery requires an activated sender-specific bilateral mapping"
}

Response 429

Explicit endpoint bucket is exhausted.

application/jsonSchemaError

Response 429 · example

{
  "code": "MUSIC_DELIVERY_RATE_LIMITED",
  "message": "Music delivery request rate exceeded; retry later"
}

Response 503

Partner delivery mutations are closed for this rollout stage or the authenticated sender is outside the active write cohort.

application/jsonSchemaError

Response 503 · example

{
  "code": "MUSIC_V2_PARTNER_WRITES_DISABLED",
  "message": "Partner delivery writes are not enabled for this rollout stage"
}