Quickstart

From a brand-new sandbox account to a live release delivered to every DSP — in about 5 minutes of copy-paste. Every step runs against the real sandbox; lifecycle webhooks fire on the real channels. When you're ready for production, swap api-sandbox.tonegrid.pro/api/v1 → api.tonegrid.pro/v1 and the same flow ships music for real.

timer ~5 minutes science sandbox-safe (no real money / no real DSP push) code copy-paste curl

Set these env vars first

export API="https://api-sandbox.tonegrid.pro/api"
export TG="<your tgk_ sandbox API key — see step 1>"
export REL=""             # release UUID — populated after step 3
export TRACK=""           # track UUID — populated after step 4

Get your sandbox API key

1 min

Every call authenticates with a tgk_ API key sent as a Bearer token. There is no self-service signup endpoint: keys are issued per workspace. Workspace owners on the Pro, Scale, API Pro and API Scale plans (see API pricing) create, rotate and revoke keys under Dashboard → API Keys; on other plans, ask ToneGrid support and we will issue one. Use the Sandbox key while you build. Sandbox is isolated from production: no real money and no real store deliveries, but the full lifecycle is simulated.

bash

curl "https://api-sandbox.tonegrid.pro/api/v1/users/me" \
  -H "Authorization: Bearer $TG"

expected response

{
  "success": true,
  "data": {
    "user": { "uuid": "u-9f3a...", "email": "you@example.com", "role": "owner" }
  }
}

lightbulb

The raw key is shown once when it is created. Store it in your secret manager straight away: we keep only a hash, so a lost key cannot be recovered, only revoked and replaced. Keep keys server-side and never ship one in browser or mobile code.

Create an artist

An artist is the named entity all releases roll up under. Slugs are unique per tenant.

bash

curl -X POST "https://api-sandbox.tonegrid.pro/api/v1/artists" \
  -H "Authorization: Bearer $TG" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Okafor",
    "slug": "ada-okafor"
  }'

expected response

{
  "success": true,
  "data": {
    "uuid": "a-3c2b...",
    "name": "Ada Okafor",
    "slug": "ada-okafor"
  }
}

lightbulb

Capture the artist uuid — you'll attach releases to it in the next step.

Create a release (draft)

1 min

New releases start in draft. You can edit freely until you call /submit. Set a release date at least 7 days in the future to give DSPs ingest lead time.

bash

curl -X POST "https://api-sandbox.tonegrid.pro/api/v1/releases" \
  -H "Authorization: Bearer $TG" \
  -H "Content-Type: application/json" \
  -d '{
    "title":         "Midnight in Lagos",
    "type":          "ep",
    "artist_id":     "a-3c2b...",
    "release_date":  "2026-06-17",
    "primary_genre": "Afrobeats",
    "language":      "en",
    "upc":           "195497123456"
  }'

expected response

{
  "success": true,
  "data": {
    "uuid":   "r-12a3...",
    "status": "draft",
    "title":  "Midnight in Lagos",
    "type":   "ep",
    "release_date": "2026-06-17"
  }
}

lightbulb

Pass localized_titles as a BCP-47 keyed object (eg {"fr": "...", "yo": "..."}) and ToneGrid will emit per-locale DisplayTitle blocks in the DDEX automatically.

Add a track + upload audio

1 min

Track metadata first, then upload the audio file. Files over 100 MB trigger AWS S3 Multipart Upload automatically (peak memory pinned at 16 MB regardless of file size).

bash

# 1. Create the track row
curl -X POST "https://api-sandbox.tonegrid.pro/api/v1/releases/$REL/tracks" \
  -H "Authorization: Bearer $TG" \
  -d '{
    "title":            "Lagos Skyline",
    "artist_id":        "a-3c2b...",
    "isrc":             "NGTON2600001",
    "duration_seconds": 218,
    "track_number":     1
  }'

# 2. Upload the audio (multipart form-data, field name `audio`)
curl -X POST "https://api-sandbox.tonegrid.pro/api/v1/tracks/$TRACK/audio" \
  -H "Authorization: Bearer $TG" \
  -F "audio=@./lagos-skyline.wav"

expected response

{
  "success": true,
  "data": {
    "uuid":            "t-5d4c...",
    "title":           "Lagos Skyline",
    "isrc":            "NGTON2600001",
    "audio_format":    "WAV",
    "audio_bit_depth": 24,
    "audio_sample_rate_hz": 96000,
    "audio_channels":  2,
    "audio_md5":       "d41d8cd98f00b204e9800998ecf8427e"
  }
}

lightbulb

ffprobe runs on the uploaded file and back-fills audio_format / sample-rate / bit-depth / channels / MD5 in ~5 seconds. Then the audio-validator gates: tracks under 44.1 kHz / 16-bit / 2 channels are auto-rejected.

Attach DSPs

Tell ToneGrid which stores to ship to. List all active DSPs via GET /dsps first.

bash

curl -X POST "https://api-sandbox.tonegrid.pro/api/v1/releases/$REL/dsps" \
  -H "Authorization: Bearer $TG" \
  -d '{
    "dsps": ["spotify", "apple-music", "amazon-music", "youtube-music", "tidal", "deezer", "tiktok", "audiomack", "boomplay"]
  }'

expected response

{
  "success": true,
  "message": "9 DSP(s) attached.",
  "data": {
    "attached": ["spotify","apple-music","amazon-music","youtube-music","tidal","deezer","tiktok","audiomack","boomplay"]
  }
}

lightbulb

Pass per-DSP overrides (territory, monetization, pricing, release-date) via PUT /releases/:uuid/dsps/:dsp_slug AFTER attaching — useful for Japan-only physical exclusives, US-only pre-orders, etc.

Validate the DDEX before approving (optional but recommended)

Run the generated NewReleaseMessage through the official DDEX ERN 4.3 XSD validator. Catches schema-breaking metadata before any DSP sees it.

bash

curl "https://api-sandbox.tonegrid.pro/api/v1/releases/$REL/ddex/validate/spotify" \
  -H "Authorization: Bearer $TG" | jq .data.validation

expected response

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

lightbulb

Hook this into your CI: if validation.valid !== true, surface the per-error line/column/message in your release-approval UI and block the user from submitting. Most aggregators ship blind — ToneGrid lets you XSD-check before push.

Approve + watch the lifecycle flow

2 min

Approving a release queues per-DSP delivery and fires release.dsp.<slug>.submitted for each one. The DDEX worker advances rows through submitted → accepted → live over ~2 minutes (sim mode); on real DSPs it's identical but driven by real ingestion ACKs.

bash

# 1. Approve
curl -X POST "https://api-sandbox.tonegrid.pro/api/v1/releases/$REL/approve" \
  -H "Authorization: Bearer $TG" \
  -H "Idempotency-Key: approve-$REL-$(date +%s)"

# 2. Watch the per-DSP delivery state
watch -n 10 "curl -s -H \"Authorization: Bearer $TG\" \
  https://api-sandbox.tonegrid.pro/api/v1/releases/$REL/ddex/deliveries | jq .data.deliveries"

expected response

// Right after approve:
{ "dsp": "spotify",      "status": "submitted" }
{ "dsp": "apple-music",  "status": "submitted" }
{ "dsp": "tidal",        "status": "submitted" }
// ... 9 rows

// T+1 min:  status flips to "accepted" + release.dsp.<slug>.accepted webhook fires
// T+2 min:  status flips to "live" + dsp_release_id populated + release.dsp.<slug>.live fires
{ "dsp": "spotify",      "status": "live", "dsp_release_id": "SIM-spot-9f3a2c", "live_at": "2026-06-17T00:02:11Z" }

lightbulb

Subscribe to webhooks via POST /webhooks with events: ["release.dsp.*.*"] to be pushed every transition instead of polling. Use the webhook tester to verify your HMAC signature handling before going live.

Preview the literal XML being shipped

See the exact NewReleaseMessage XML each DSP receives. This is the supply-chain proof — what you see is byte-identical to what lands at the DSP's ingestion endpoint.

bash

curl -O -J "https://api-sandbox.tonegrid.pro/api/v1/releases/$REL/ddex/preview/spotify.xml" \
  -H "Authorization: Bearer $TG"

# saves: $REL-spotify.xml

# Or get JSON envelope with sha256:
curl "https://api-sandbox.tonegrid.pro/api/v1/releases/$REL/ddex/preview/spotify" \
  -H "Authorization: Bearer $TG" | jq '.data | {sha256, size_bytes, message_type}'

expected response

{
  "sha256":       "9f4a1c2e88d3b7c6e2a4f1d5c8b9e0f7a6c4d2b1e3a8f5c7d9b1e6a2f4c8d3a5",
  "size_bytes":   12648,
  "message_type": "NewReleaseMessage"
}

lightbulb

For takedowns use POST /releases/:uuid/ddex/purge (PurgeReleaseMessage); for metadata corrections use POST /releases/:uuid/ddex/redeliver (re-pushes NewReleaseMessage on the same MessageThreadId). Both are in the DDEX section.

That's it. You shipped a release.

The same flow runs unchanged on production — swap the host, plug in your prod API key, and you're shipping real music to real stores. Subscribe to webhooks (or verify your signature handling first) and you're done.

verified Verify webhook signatures webhook Subscribe to webhooks terminal Open Explorer report Errors catalogue