Glossary

The token format used for ToneGrid API authentication. A signed, base64-encoded payload containing the user's uuid, role, tenant_id, and expiry claim. Pass as Authorization: Bearer <token> on every authenticated request.

A top-level account container within ToneGrid — typically a record label or distributor. All resources (releases, artists, royalties) are strictly scoped to a tenant. A user's tenant_id is embedded in their JWT and enforced on every request.

Each user is assigned one role that governs which endpoints they may call.

List endpoints return paginated results. Pass page (default 1) and per_page (default 20, max 100) as query parameters. Responses include a total count alongside the data array.

Limits applied per authenticated user per minute to ensure platform stability. Exceeding the limit returns 429 Too Many Requests. Check the Retry-After response header for how many seconds to wait before retrying.

An HTTP POST sent by ToneGrid to a URL you configure whenever a notable event occurs — e.g. release approved, DDEX delivery acknowledged, or royalty statement created. Payloads are signed with an HMAC-SHA256 secret.

Every webhook delivery includes X-ToneGrid-Signature: t=<unix_ts>,v1=<hex>. Verify by computing HMAC-SHA256(secret, ts + "." + raw_body) and constant-time comparing to v1. Replay attacks are blocked by validating the timestamp is recent.

Co-arrives with X-ToneGrid-Event and X-ToneGrid-Delivery-Id on every webhook fire so your verifier can authenticate the payload before processing.

Long-lived token issued from your dashboard, prefixed tgk_. Use as Authorization: Bearer tgk_… for server-to-server integrations. Stored as SHA-256 hash; cannot be retrieved after the create response. Rotate via the dashboard.

Opaque string you choose, scoped per tenant. If the same key is sent again inside 24 h with the same body, ToneGrid replays the stored response with X-ToneGrid-Idempotent-Replay: true. A different body returns 422.

List endpoints accept ?cursor=opaque instead of ?page=N. Performance does not degrade with depth (no OFFSET). Response carries meta.next_cursor and a Link: <…>; rel="next" header. Treat the cursor as opaque; encoding may change.

Optional request header you set; propagated through ToneGrid's audit log and worker logs. If omitted, the server generates one. Include the value when reporting a 5xx for fast log lookup.

A single, EP, album, or compilation submitted for distribution to DSPs. A release contains one or more tracks and carries a UPC. Releases move through a defined status lifecycle before going live.

An individual audio recording within a release. Each track has a unique ISRC, a track number, and an audio asset. Tracks can carry lyrics, explicit flags, and per-artist royalty splits.

A named performer or group associated with releases. Each artist has a unique URL-safe slug, optional Spotify URI, and Apple Music Artist ID used to link profiles across DSPs.

A 12-digit barcode assigned to a release (album, EP, or single) as a whole. Also referred to as EAN-13 in some regions. ToneGrid auto-assigns a UPC when not provided at release creation.

A 12-character alphanumeric code that uniquely identifies a specific recording (track). Format: CC-XXX-YY-NNNNN. ToneGrid auto-assigns ISRCs when not provided, or you can supply your own registered codes.

The percentage of net royalties assigned to each rights-holder on a track. All splits on a track must sum to exactly 100. Set via PUT /tracks/:uuid/splits.

JSON array of codes describing what makes the track distinct: remix, samples_or_stock, mix_or_compilation, alternate_version, special_genre, non_musical, includes_ai. DSPs use these for classification + content-safety.

Three asset types per release: square_motion (1:1 Apple Motion Artwork), tall_motion (3:4 Apple Motion Artwork), canvas_loop (9:16 Spotify Canvas). Upload at POST /releases/:uuid/animated-artwork/:asset_type. MP4 / MOV / WebM / GIF, ≤50 MB.

Submit an Atmos master alongside the stereo via tracks.dolby_audio_url + separate tracks.dolby_isrc. Master format: ADM BWF, 48 kHz, ≥3 channels, ≤2 GB, matching stereo duration. DDEX 4.3 emits ImmersiveAudio with format DolbyAtmos.

The container required by Apple, Amazon, and Tidal for Dolby Atmos masters. Carries spatial metadata in a <chna> chunk. Binaural rendering happens DSP-side.

Plain-text lyric format with per-line timestamps: [00:23.45]First line. Set tracks.lyric_format = "lrc" and submit lyrics text. Apple, Spotify, Tidal all accept LRC for line-by-line karaoke playback.

XML-based timed-text format used by Apple Music for word-level synced lyrics. Set tracks.lyric_format = "ttml" or "word_by_word" and submit the TTML/iTT document in localized_lyrics keyed by BCP-47 locale.

The locale code format used everywhere in ToneGrid: en, en-US, fr-CA, ja, yo, ig, ha, sw, zh-CN, ar, etc. Used as the key in localized_titles / localized_lyrics / etc. and emitted into DDEX as @LanguageAndScriptCode.

Per-release BCP-47 code that determines which title and description win when a DSP ingests only one language (Spotify, Apple). Default en. Must be a key in localized_titles when both are supplied.

Per-release setting in release_rights.ai_disclosure: none, partial (AI-assisted), material (substantial AI), full (fully AI-generated). DSPs use the flag for labelling and rights routing.

Per-track flag album_only=true tells DSPs the track may only stream / sell as part of the album, never as an individual single. Used for deep-cut album tracks.

A track from a pre-order release that becomes available immediately upon purchase, before the album drops. Encourages pre-orders. Configured at submission.

A platform that distributes and monetises digital music — e.g. Spotify, Apple Music, Boomplay, Audiomack, YouTube Music. ToneGrid delivers releases to DSPs via DDEX ERN messages or direct API integrations depending on the DSP's capabilities.

A country or region where a release is available for streaming. Represented as ISO 3166-1 alpha-2 codes (e.g. NG, US, GB). Use WW to indicate worldwide availability with optional exclusions.

The state of a release's journey to a DSP.

The removal of a release from one or more DSPs. ToneGrid sends a DDEX PurgeReleaseMessage to each targeted DSP. Takedowns are irreversible via the API — re-distribution after a takedown requires a new delivery request.

A time-limited URL granting direct upload access to ToneGrid's S3 storage without routing audio through the API server. Obtain via POST /tracks/presign. The URL expires after 60 minutes.

The process of moving release ownership between accounts or labels within ToneGrid. Transfers require acceptance by the receiving party within 72 hours. DSP delivery attribution is updated automatically upon acceptance.

One row per inbound release submission, regardless of channel (REST JSON / DDEX ERN XML / CSV bulk / JSON bulk / SFTP drop / partner webhook push). Browse via GET /ingestion/jobs. State machine: received → queued → parsing → validating → staged → accepted | rejected | failed.

ToneGrid packages the DDEX bundle and pushes it straight to the DSP's ingestion endpoint — SFTP for most majors (Spotify, Apple, Tidal), REST for YouTube Music / TikTok / Instagram. No aggregator hop. Visible per-DSP via GET /supply-chain/dsps with delivery_method = "ddex_sftp_direct" or "ddex_rest_direct".

For certain long-tail regional DSPs, ToneGrid routes deliveries through a licensed delivery partner. The partner relationship is treated as proprietary supply-chain plumbing — clients see delivery_method = "partner_routed" per DSP but never the partner's identity.

A delivery arrangement where the rights-holder maintains their own direct contract with the DSP (signing for revenue terms) while ToneGrid handles the technical delivery. Common for large labels that want their own DSP relationships but outsource ingestion plumbing.

Which commercial models a release supports: ad_supported_streaming, subscription_streaming, permanent_download, conditional_download, ringtone, ringback_tone, ugc_monetization, restricted. Set via PUT /supply-chain/releases/:uuid/monetization.

One of back_catalog, budget, mid, front_line, premium, custom. Maps to per-DSP local-currency price ladders. Custom carries explicit per-track + per-album amounts plus an ISO 4217 currency.

Set territory_mode to worldwide, include (carries an allow-list of ISO 3166-1 alpha-2 codes), or exclude (carries a block-list). Per-DSP overrides further restrict.

The result of merging release-level supply-chain config with per-DSP overrides. GET /supply-chain/releases/:uuid/effective-config returns the literal pricing, territory, monetization, and rights state that will land in each DSP's DDEX bundle. The "what each DSP actually sees" proof.

Override any combo of pricing tier, territory, monetization policies, rights flags, release-date, or is_blocked for one DSP without touching the release-level config. PUT/DELETE at /supply-chain/releases/:uuid/dsps/:slug/overrides.

Returned by GET /supply-chain/releases/:uuid/delivery-plan — every DSP attached to the release with its delivery_method, ddex_ern_version, ingestion protocol, certification level, and current status. The supply-chain transparency endpoint.

An international standards body that defines XML message formats for communicating music business transactions between parties — distributors, DSPs, rights societies, and publishers. ToneGrid implements DDEX ERN 4.1 for all release deliveries.

The primary DDEX message type for delivering release and track metadata to a DSP. A NewReleaseMessage creates or updates a release; a PurgeReleaseMessage requests its removal. ToneGrid generates ERN 4.1 messages automatically on distribution.

A unique identifier registered with the DDEX Metadata Office (MO) that identifies a party in a DDEX transaction — e.g. ToneGrid's DPID as the sender, and each DSP's DPID as the receiver of an ERN message.

A structured code used within DDEX messages to globally identify a release. Format: A1-XXXXX-YYYYYYYYYYY-Z. ToneGrid generates GRids automatically and embeds them in all ERN XML messages sent to DSPs.

A response message sent by a DSP to confirm receipt and processing of a DDEX ERN message. ACK status values: Accepted (processed successfully), Rejected (message had errors), Pending (still under DSP review).

The XML message type used for new releases and metadata updates. Wraps all release, track, rights, and territory data in a structured schema conforming to DDEX ERN 4.3. Contrast with PurgeReleaseMessage which triggers a takedown.

ToneGrid emits ERN 4.3 by default — the current major-DSP standard. Per-DSP fallback to ERN 4.2 or 3.8.2 is configured server-side when a DSP hasn't upgraded yet. Preview the literal XML for any DSP via GET /releases/:uuid/ddex/preview/<dsp>.xml.

ToneGrid uses ERN-Direct (SFTP or REST push directly to the DSP). Other DDEX choreographies — ERN-Cloud (S3-staged), ERN-FTP, ERN-Web (Atom feed) — are supported on request per DSP.

DDEX standard for marketing assets (artist bios, mood / theme tags, image gallery, focus tracks). Sent alongside ERN to feed DSP editorial systems.

DDEX standard for canonical Party records — artists, publishers, labels with stable PartyIds, ISNIs, IPI numbers. Lets DSPs deduplicate across deliveries.

DDEX standard for studio-level session metadata — performers, engineers, instruments, recording dates. Carries the credit detail that becomes Apple Music / Spotify "Credits" tab.

Globally unique identifier for a DDEX participant (sender or recipient). Format PADPIDA + 12 alphanumeric chars. ToneGrid's DPID appears as MessageSender/PartyId; the DSP's DPID as MessageRecipient/PartyId in every bundle.

A document summarising an artist's earned royalties over a billing period. Includes gross_revenue (total earned from DSPs) and net_revenue (after platform fees). Statements require label_admin approval before payment.

The amount payable to rights-holders after ToneGrid's platform fees have been deducted from gross revenue. Gross revenue represents the total received from DSPs before any deductions.

A single row within a royalty statement representing earnings from a specific track on a specific DSP in a specific territory. Line items carry streams, gross_amount, and net_amount.

Monthly / quarterly / annual / adhoc bucket for sales reports + statements. Period state machine: open → closing → closed → paid. Reference periods by their code (e.g. 2026-04, 2026-Q1).

Statement scoped to one payee (artist / songwriter / label / publisher / external). Carries their share, withholding, and net payable for the period. Approve via POST /finance/payee-statements/:uuid/approve before payout.

A row in payouts recording a real money movement. Rails: tipalti, paystack, wire, sepa, paypal, wise, payoneer, manual. State: pending → sent → succeeded | failed | reversed.

Returned by GET /finance/balance: available_usd_minor (approved statements not yet on a payout), in_flight_usd_minor, lifetime_paid_usd_minor, lifetime_gross_usd_minor. All amounts in USD cents to avoid float drift.

Each sales-report row records the fx_rate_to_usd applied to convert from the DSP's local-currency payout to ToneGrid's USD ledger. Locked at period close.

Amount deducted from the payee's gross share to satisfy tax obligations (US-resident 1099, non-resident treaty rates, VAT, etc.). Carried on every payee_statement as total_withholding_usd_minor.

A boolean flag on a release or track indicating the presence of explicit language or mature themes. When set, DSPs display a parental advisory label. Set at both release level and track level — track-level takes precedence.

A two-letter code identifying the primary language of a release or track (e.g. en for English, fr for French, yo for Yoruba). Used in the DDEX ERN message to communicate language metadata to DSPs.

A two-letter code identifying a country for territory and analytics purposes (e.g. NG for Nigeria, US for United States). The special code WW (Worldwide) is used in ToneGrid to indicate global availability.

A three-letter code identifying a currency used in royalty statements (e.g. USD, GBP, NGN). ToneGrid defaults to USD unless another currency is specified when creating a royalty statement.

A string field on a release describing the primary musical genre (e.g. Afrobeats, Hip-Hop, Amapiano). Max 80 characters. DSPs use this for editorial categorisation and playlist recommendations.

The 4-digit year in which the audio recording was originally produced. Distinct from the release date. Communicated to DSPs as the phonographic copyright year (℗) in DDEX ERN messages.

The sound-recording copyright statement, e.g. ℗ 2026 Lagos Sound Recordings. Holds the rights in the recorded performance, not the underlying composition. Distinct from the C-line.

The musical-composition copyright statement, e.g. © 2026 Lagos Sound Publishing. Holds the rights in the underlying song. Held by the publisher / songwriter, not the label.

Required when a track records someone else's composition (covers, samples). Cleared via the HFA, MLC, MCPS-PRS, Easy Song, or direct from the publisher. Recorded on the release: mech_license_held + mech_license_provider.

Globally unique identifier for a musical composition (vs ISRC which identifies a recording). Format T-NNNNNNNNN-X. Sit on writers + per-track via tracks.iswc and the track-writer join.

16-digit globally unique ID for a public-identity entity — artist, writer, publisher, performer. Lets DSPs deduplicate "John Smith" across releases. Carry on writers, publishers, and track collaborators.

As of 2025, Spotify / Apple / Tidal require disclosure of generative-AI involvement in audio, vocals, or artwork. ToneGrid surfaces this via release_rights.ai_disclosure and per-track track_properties "includes_ai". Non-disclosure may trigger DSP takedowns.

First-class tenant-scoped entity carrying ISWC, IPI name number, PRO affiliation, ISNI. CRUD via /writers. Attach to tracks via PUT /tracks/:uuid/writers; composer shares must sum to exactly 100 across all writers on a track.

First-class tenant-scoped entity for the publishing side. Carries IPI, PRO affiliation, ISNI, is_controlled (in-house vs external), and mech_license_via. Attach per writer or per whole composition via PUT /tracks/:uuid/publishers with optional per-territory share splits.

27-role enum covering everyone whose contribution lands in liner notes: producer, executive producer, mix engineer, mastering engineer, featured artist, vocalist, instrumentalist (with role_detail), arranger, conductor, remixer, DJ, A&R, photographer, illustrator, etc. PUT /tracks/:uuid/collaborators.

9-11 digit identifier issued by the writer's or publisher's PRO; uniquely identifies an interested party in royalty pools globally. Required for accurate composition-side payouts. Sit on the writer + publisher rows.

The body that collects performance royalties on behalf of writers / publishers — ASCAP, BMI, SESAC, GMR (US), PRS (UK), SACEM (FR), GEMA (DE), JASRAC (JP), COSON / MCSN (NG), etc. Always carried per writer / publisher row so DDEX can route the composition-side accounting.

Each writer on a track gets a composer_share_percent (0-100). All composer shares on a single track MUST sum to exactly 100, validated server-side on every PUT. Distinct from master_share_percent (usually 0 for writers — held by the label).

Per-collaborator integer that controls billing order in liner notes / DSP credits tabs. Producer = 1, featured artist = 2, etc. Default order = upload order.

While ToneGrid is finalising the technical integration for a given DSP, that DSP's deliveries run on a simulated lifecycle (submitted → accepted → live within a few minutes) so client integrations behave identically to live delivery. Switchover to live push is automatic per DSP; client code never changes.

submitted (bundle sent) → accepted (DSP acknowledged) → live (live on storefront). Each transition fires release.dsp.<slug>.<stage> webhook. Failures stop at rejected / error. Takedowns flow live → taken_down.

Full-fidelity copy of the API at https://api-sandbox.tonegrid.pro/api. Separate DB, separate JWT secret, same endpoints, simulated DSP delivery. Identifying response header: X-Tonegrid-Env: api-sandbox.

Live at https://api-docs.tonegrid.pro/status. Probes the API, sandbox, docs, and OpenAPI spec; parses worker logs for last-run timestamps; surfaces an overall health banner.

Every API response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. 429 responses additionally carry Retry-After in seconds. Per-token bucket, refilled per minute.