ToneGrid API Reference

Same XML the preview endpoint returns, but additionally run through the official DDEX ERN 4.3 XSD validator (release-notification.xsd). Response includes a validation block listing every schema error with line, column, severity, and message. Returns validation.valid = true when the document is fully schema-clean.

curl "https://api.tonegrid.pro/releases/$UUID/ddex/validate/apple-music" \
  -H "Authorization: Bearer $TG_TOKEN" | jq .data.validation

{
  "valid":       true,
  "errors":      [],
  "xsd_path":    "/opt/ddex-schemas/ern43/release-notification.xsd",
  "ern_version": "4.3"
}

{
  "valid":       false,
  "errors": [
    {
      "level":   "error",
      "line":    68,
      "column":  0,
      "message": "Element 'BitRate', attribute 'UnitOfMeasure': The value 'Kbps' is not an element of the set {'bps', 'Gbps', 'kbps', 'Mbps'}."
    }
  ],
  "ern_version": "4.3"
}

Queues delivery to every DSP attached to the release. Honours per-DSP is_blocked overrides (those are skipped, reported in the response). Returns 202 with the per-DSP queue state and fires release.dsp.<slug>.submitted webhook for each.

curl -X POST "https://api.tonegrid.pro/releases/$UUID/ddex/deliver" \
  -H "Authorization: Bearer $TG_TOKEN" \
  -H "Idempotency-Key: deliver-$UUID-$(date +%s)"

{
  "success": true,
  "message": "3 DSP(s) queued for direct DDEX delivery.",
  "data": {
    "queued":  [
      { "dsp": "spotify",     "state": "submitted" },
      { "dsp": "apple-music", "state": "submitted" },
      { "dsp": "tidal",       "state": "submitted" }
    ],
    "skipped": [
      { "dsp": "youtube-music", "reason": "is_blocked" }
    ]
  }
}

Same as above but scoped to a single DSP. Useful for re-deliveries, takedown follow-ups, or DSP-by-DSP backfills. Returns 409 if the DSP has is_blocked = true on this release.

Use when the metadata for an already-live release has changed (typo, new contributor, swapped cover). The worker pushes a fresh NewReleaseMessage to every attached DSP, reusing the original MessageThreadId so the DSP correlates it as an update to the prior delivery — not a brand-new release. Avoids losing stream attribution and ISRC continuity.

curl -X POST "https://api.tonegrid.pro/releases/$UUID/ddex/redeliver" \
  -H "Authorization: Bearer $TG_TOKEN" \
  -H "Idempotency-Key: redeliver-$UUID-$(date +%s)"

Returns the literal DDEX ERN 4.3 PurgeReleaseMessage the worker would push to this DSP. Append .xml to download as a raw .xml file. Validates against the official XSD.

<ern:PurgeReleaseMessage xmlns:ern="http://ddex.net/xml/ern/43"
                         AvsVersionId="2022"
                         LanguageAndScriptCode="en">
  <MessageHeader>
    <MessageThreadId>TG-THREAD-08bbb9acb793932b36dad693</MessageThreadId>
    <MessageId>TG-PURGE-2e985218e6a526bde64d5505be72</MessageId>
    <MessageFileName>TG_purge_spotify_a1b2c3d4_20260518174650.xml</MessageFileName>
    <MessageSender>
      <PartyId>PADPIDA2026012301U</PartyId>
      <PartyName><FullName>ToneGrid</FullName></PartyName>
    </MessageSender>
    <MessageRecipient>
      <PartyId>PADPIDA2014020404J</PartyId>
      <PartyName><FullName>Spotify</FullName></PartyName>
    </MessageRecipient>
    <MessageCreatedDateTime>2026-05-18T17:46:50Z</MessageCreatedDateTime>
    <MessageControlType>LiveMessage</MessageControlType>
  </MessageHeader>
  <PurgedRelease>
    <ReleaseId>
      <GRid>A12425GABC1234567X</GRid>
      <ICPN>195497123456</ICPN>
      <ProprietaryId Namespace="tonegrid.pro">a1b2c3d4-e5f6-7890-abcd-ef1234567890</ProprietaryId>
    </ReleaseId>
    <Title><TitleText>Midnight in Lagos</TitleText></Title>
  </PurgedRelease>
</ern:PurgeReleaseMessage>

Same as /ddex/validate but for the PurgeReleaseMessage variant. Returns validation.valid = true when schema-clean. Use in CI before queueing a takedown.

Hard takedown across every attached DSP. Each row flips to takedown_submitted and fires release.dsp.<slug>.takedown_submitted. The worker then pushes the PurgeReleaseMessage; on success the row becomes taken_down and release.dsp.<slug>.taken_down fires (with message_type: PurgeReleaseMessage).

Per-DSP variant. Useful for selective takedowns — e.g. pull from one DSP that flagged the release while leaving it live everywhere else.

For every DSP attached to the release: current status (pending / submitted / live / rejected / taken_down / error), DSP-assigned release ID, live URL, submitted_at, live_at, error_message, updated_at.

curl "https://api.tonegrid.pro/releases/$UUID/ddex/deliveries" \
  -H "Authorization: Bearer $TG_TOKEN"

{
  "success": true,
  "data": {
    "release_id": "a1b2c3d4-...",
    "deliveries": [
      {
        "uuid":           "del-9ab1...",
        "dsp":            "spotify",
        "dsp_name":       "Spotify",
        "status":         "live",
        "dsp_release_id": "spotify:album:7v0Y...",
        "live_url":       "https://open.spotify.com/album/7v0Y...",
        "submitted_at":   "2026-06-17T00:00:14Z",
        "live_at":        "2026-06-17T00:02:11Z",
        "error_message":  null,
        "updated_at":     "2026-06-17T00:02:11Z"
      }
    ]
  }
}

Creates a new catalog transfer request. The receiving party gets a notification and must accept within 72 hours, after which the transfer expires.

Body parameters

curl https://api.tonegrid.pro/transfers \
  -X POST \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "to_account_uuid": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "releases": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "message": "Artist moving to new label. Please accept ownership of listed releases."
  }'

{
  "transfer": {
    "uuid":            "f6a7b8c9-d0e1-2345-fabc-678901234567",
    "status":          "pending",
    "from_account":    "label@example.com",
    "to_account_uuid": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "release_count":   1,
    "expires_at":      "2026-04-29T11:00:00Z",
    "created_at":      "2026-04-26T11:00:00Z"
  }
}

Returns paginated transfer requests — both sent and received — filtered by direction and status.

Query parameters

curl "https://api.tonegrid.pro/transfers?direction=received&status=pending" \
  -H "Authorization: Bearer <access_token>"

{
  "data": [
    {
      "uuid":          "f6a7b8c9-d0e1-2345-fabc-678901234567",
      "status":        "pending",
      "from_account":  "oldlabel@example.com",
      "release_count": 1,
      "expires_at":    "2026-04-29T11:00:00Z",
      "created_at":    "2026-04-26T11:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Retrieves a single transfer request including the full list of releases included in the transfer.

curl "https://api.tonegrid.pro/transfers/f6a7b8c9-d0e1-2345-fabc-678901234567" \
  -H "Authorization: Bearer <access_token>"

{
  "transfer": {
    "uuid":          "f6a7b8c9-d0e1-2345-fabc-678901234567",
    "status":        "pending",
    "from_account":  "oldlabel@example.com",
    "to_account":    "newlabel@example.com",
    "message":       "Artist moving to new label.",
    "release_count": 1,
    "releases": [
      { "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Eclipse", "type": "single" }
    ],
    "expires_at":  "2026-04-29T11:00:00Z",
    "created_at":  "2026-04-26T11:00:00Z"
  }
}

Accepts a pending transfer. Ownership of all included releases is immediately transferred to the accepting account. DSP deliveries are re-attributed. Only the receiving account can accept.

curl "https://api.tonegrid.pro/transfers/f6a7b8c9-d0e1-2345-fabc-678901234567/accept" \
  -X POST \
  -H "Authorization: Bearer <access_token>"

{ "message": "Transfer accepted. 1 release(s) transferred to your account." }

Declines a pending transfer request. The sending account is notified. The transfer moves to declined status and cannot be re-activated.

curl "https://api.tonegrid.pro/transfers/f6a7b8c9-d0e1-2345-fabc-678901234567/decline" \
  -X POST \
  -H "Authorization: Bearer <access_token>"

{ "message": "Transfer declined." }

Returns every event you can subscribe to plus the supported wildcard patterns. Per-DSP events follow release.dsp.<dsp_slug>.<stage> where stage is one of submitted, accepted, rejected, live, taken_down, failed.

{
  "success": true,
  "data": {
    "events": [
      "release.created",
      "release.submitted",
      "release.dsp.spotify.submitted",
      "release.dsp.spotify.accepted",
      "release.dsp.spotify.live",
      "release.dsp.applemusic.live",
      "release.dsp.youtubemusic.live",
      "ingestion.received",
      "ingestion.accepted",
      "ingestion.rejected",
      "royalty_statement.ready"
    ],
    "wildcards": {
      "*":                        "Subscribe to every event.",
      "release.dsp.*.live":       "Every DSP go-live event.",
      "release.dsp.spotify.*":    "Every Spotify lifecycle event.",
      "ingestion.*":              "Every inbound ingestion event."
    }
  }
}

Returns the raw tgwhsec_… secret once. Store it server-side; you'll need it to verify signatures. Limit: 25 active subscriptions per tenant.

curl -X POST https://api.tonegrid.pro/webhooks \
  -H "Authorization: Bearer tgk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production hook",
    "url":  "https://example.com/tonegrid/webhook",
    "events": ["release.dsp.*.live", "ingestion.*", "royalty_statement.ready"],
    "description": "Notify our backend when DSPs go live"
  }'

{
  "success": true,
  "message": "Webhook created. Store the secret now — it will not be shown again.",
  "data": {
    "uuid": "9a8b...c1d0",
    "name": "Production hook",
    "url":  "https://example.com/tonegrid/webhook",
    "secret_prefix": "tgwhsec_a1b2c3d",
    "secret": "tgwhsec_a1b2c3d4e5f6...long-secret-only-shown-now",
    "events": ["release.dsp.*.live","ingestion.*","royalty_statement.ready"],
    "is_active": true
  }
}

Triggers webhook.test against the subscription. Add webhook.test (or *) to its events list to receive it.

Per-attempt log with status (queued / sending / succeeded / failed / dead), response code, body, error message, duration_ms, retry count, scheduled_at.

Old secret invalid immediately. New tgwhsec_… returned in response. Update your verifier before the next event fires.

Atomic: release + every track is created in one transaction. Returns 201 with the release object and a job UUID for traceability.

curl -X POST https://api.tonegrid.pro/ingestion/json \
  -H "Authorization: Bearer tgk_..." \
  -H "Idempotency-Key: client-release-001" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Midnight in Lagos",
    "type":  "ep",
    "genre": "Afrobeats",
    "release_date": "2026-07-12",
    "upc": "0123456789012",
    "explicit_content": false,
    "tracks": [
      {"title":"Opening","track_number":1,"duration_seconds":215,"isrc":"USRC12345678"},
      {"title":"Lagos Nights","track_number":2,"duration_seconds":192,"isrc":"USRC12345679"}
    ]
  }'

{
  "success": true,
  "message": "Release ingested via rest_json — 2 tracks created.",
  "data": {
    "ingestion_job_id": "7a3c...d910",
    "release": { "uuid": "a1b2-...", "title": "Midnight in Lagos", "type": "ep" },
    "tracks":  [ { "uuid": "...", "title": "Opening" }, { "uuid": "...", "title": "Lagos Nights" } ]
  }
}

Submit up to 200 releases in one call. Each becomes its own job, processed by the worker. Returns 202 with the list of job UUIDs to poll or subscribe to.

Send the DDEX NewReleaseMessage as either raw XML body (Content-Type: application/xml) or multipart field ddex_xml. We sniff the ERN version + MessageId, stage the bundle, and queue it for the worker.

curl -X POST https://api.tonegrid.pro/ingestion/ddex \
  -H "Authorization: Bearer tgk_..." \
  -H "Content-Type: application/xml" \
  --data-binary @release-bundle.xml

{
  "success": true,
  "message": "DDEX bundle received. Track status via GET /ingestion/jobs/7a3c...",
  "data": {
    "ingestion_job_id": "7a3c...d910",
    "state": "received",
    "ddex_message_id": "PADPID-MSG-2026-07-12-001",
    "ddex_ern_version": "4.3"
  }
}

Multipart upload field releases_csv. Required header columns: title, track_title. Optional: type, genre, release_date, upc, isrc, track_number, duration_seconds, audio_url, artist_name, explicit, language. Rows with the same title become tracks of one release.

State transitions: received → queued → parsing → validating → staged → accepted | rejected | failed. Includes manifest file refs, DDEX MessageId/ERN version, error_code + validation_errors when rejected, and the resulting release_id when accepted.

Every active DSP labelled with its delivery method, DDEX ERN version, ingestion protocol, certification level, and territory set. Direct DDEX feeds are marked delivery_method: "ddex_sftp_direct" or "ddex_rest_direct".

{
  "success": true,
  "data": {
    "dsps": [
      { "slug": "spotify",      "name": "Spotify",       "delivery_method": "ddex_sftp_direct", "ddex_ern_version": "4.3",   "certification_level": "preferred_provider_platinum", "supports_atmos": true,  "supports_video": false, "territory_set": "global" },
      { "slug": "applemusic",   "name": "Apple Music",   "delivery_method": "ddex_sftp_direct", "ddex_ern_version": "4.3",   "certification_level": "certified",                  "supports_atmos": true,  "supports_video": true,  "territory_set": "global" },
      { "slug": "youtubemusic", "name": "YouTube Music", "delivery_method": "ddex_rest_direct", "ddex_ern_version": "4.3",   "certification_level": "certified",                  "supports_atmos": false, "supports_video": true,  "territory_set": "global" }
    ],
    "summary": { "total_active": 24, "direct_ddex_sftp": 18, "direct_ddex_rest": 4, "partner_routed": 2 },
    "note":    "Every DSP is delivered via DDEX ERN. Direct = bundle is pushed straight to the DSP's ingestion endpoint by ToneGrid."
  }
}

Returns the 8 standard codes: ad_supported_streaming, subscription_streaming, permanent_download, conditional_download, ringtone, ringback_tone, ugc_monetization, restricted. Use codes when calling PUT /supply-chain/releases/:uuid/monetization.

Six tiers: back_catalog, budget, mid, front_line, premium, custom. Each carries default per-track + per-album amounts in minor units (USD cents). custom means you supply pricing_custom_track_minor + pricing_custom_album_minor + pricing_currency.

Returns the current supply-chain configuration for a release: monetization policies, pricing tier (+ custom amounts), territory mode and codes. When unset, the response is the default config with is_default: true.

Body: {"monetization_policy_codes": ["subscription_streaming","permanent_download"]}. Validated against the catalogue.

Body: {"pricing_tier_code": "front_line"} or for custom: {"pricing_tier_code":"custom","pricing_custom_track_minor":129,"pricing_custom_album_minor":999,"pricing_currency":"USD"}.

Body: {"territory_mode":"worldwide"}, or {"territory_mode":"include","territory_codes":["NG","GH","KE","ZA"]}, or {"territory_mode":"exclude","territory_codes":["US","CA"]}. Codes are ISO 3166-1 alpha-2.

For every DSP attached to the release, shows the delivery method, DDEX ERN version, ingestion protocol, certification level, and current status. This is the supply-chain proof: clients see the literal pipeline that will execute.

Release-level config + per-DSP overrides, merged into the final state that lands in each DDEX bundle. Shows pricing, territory, monetization, rights, and the is_blocked kill-switch per DSP.

Override release-level config for a single DSP. Any subset of: pricing_tier_code, pricing_custom_*, pricing_currency, territory_mode, territory_codes, monetization_policy_codes, rights_override, is_blocked, release_date_override. DELETE the same path to clear and inherit again.

Multipart upload field asset. Replaces any existing artwork of that type (previous version soft-deleted). Dimensions / duration / codec metadata are filled in asynchronously by the asset-validation worker.

Monthly / quarterly / annual / adhoc periods with state (open → closing → closed → paid). Used as the time bucket for sales reports and statements.

Per period × DSP × release × track × country. Filters: ?period=2026-04&dsp=spotify&release=&track=&isrc=&country=. Response includes streams + downloads + gross revenue + FX rate + USD-normalized revenue + aggregate totals.

One statement per period per tenant: total streams, gross, commission, withholding, net payable. Includes the per-payee breakdown linked from payee_statements.

Artist / songwriter / publisher / external payees, with their split share, withholding tax, and net payable per period.

Actual payouts via Tipalti / Paystack / wire / SEPA / PayPal / Wise / Payoneer / manual rails. Includes external reference, state, sent_at, succeeded_at, failed_at, error_message.

Replaces the entire writer list for the track. Composer shares must sum to exactly 100% (or all be 0 to clear). Returns 422 with the running total if the math doesn't work.

curl -X PUT https://api.tonegrid.pro/tracks/{uuid}/writers \
  -H "Authorization: Bearer tgk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "writers": [
      { "writer_uuid":"…", "role":"composer_lyricist", "composer_share_percent": 60, "master_share_percent": 0 },
      { "writer_uuid":"…", "role":"composer",          "composer_share_percent": 40, "master_share_percent": 0 }
    ]
  }'

Optional for_writer_uuid links a publisher to a specific writer's share. Optional territory_codes scopes the admin deal (NULL = worldwide).

{
  "publishers": [
    {
      "publisher_uuid":   "…",
      "for_writer_uuid":  "…",
      "share_percent":    100,
      "is_administrator": true,
      "is_original_owner": false,
      "territory_codes":  ["NG","GH","KE","ZA"]
    }
  ]
}

27 role enum: producer, executive_producer, co_producer, vocal_producer, mix_engineer, mastering_engineer, recording_engineer, assistant_engineer, featured_artist, vocalist, background_vocalist, guest_artist, instrumentalist, arranger, conductor, remixer, orchestra, choir, programmer, dj, sound_designer, a_and_r, liner_notes, photographer, illustrator, styled_by, other. role_detail carries the instrument when role=instrumentalist. credit_order controls liner-notes ordering.

{
  "collaborators": [
    { "name":"Sarz",        "role":"producer",          "credit_order": 1 },
    { "name":"Tems",        "role":"featured_artist",   "credit_order": 2, "spotify_uri":"spotify:artist:..." },
    { "name":"P2J",         "role":"mix_engineer",      "credit_order": 3 },
    { "name":"Chris Gehringer","role":"mastering_engineer","credit_order": 4 },
    { "name":"Drum group",  "role":"instrumentalist",   "role_detail":"Drums", "credit_order": 5 }
  ]
}

Full replace. Send any subset of preferred_locale, localized_titles, localized_descriptions. Omitted keys are left untouched.

curl -X PUT https://api.tonegrid.pro/releases/{uuid}/localizations \
  -H "Authorization: Bearer tgk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "preferred_locale": "en",
    "localized_titles": {
      "en":    "Midnight in Lagos",
      "fr":    "Minuit à Lagos",
      "yo":    "Òjò Òru Èkó",
      "ja":    "ラゴスの真夜中",
      "zh-CN": "拉各斯午夜"
    },
    "localized_descriptions": {
      "en": "Late-night Afrobeats EP recorded in Lagos.",
      "fr": "EP afrobeats nocturne enregistré à Lagos."
    }
  }'

Per-track localized titles, title_versions, and lyrics. The DDEX bundle wires localized lyrics into <LyricsRights> alongside the per-locale title blocks. Apple synced lyrics via TTML use the localized_lyrics map keyed by BCP-47.

Role-gated by parent: platform can create any, enterprise → client | artist, client → artist, artist → nothing. Body: {name, slug, tenant_role, custom_domain?}.

Returns a short-lived Bearer token scoped to the child tenant. Use it for any follow-up call. Carries acting_as: true + on_behalf_of: <parent_uuid> claims. Every call made with the token is audit-logged.

Releases / tracks / artists counts + lifetime streams + lifetime revenue (USD minor units) for the child tenant.