{ "openapi": "3.1.0", "info": { "title": "ToneGrid API", "version": "2026-05-18", "description": "Enterprise music distribution. Direct DDEX feeds to 220+ stores. Multi-channel ingest (REST JSON, DDEX ERN XML, CSV bulk, JSON bulk, SFTP). Per-DSP supply-chain control. Real-time webhook events naming every DSP at every lifecycle stage.\n\n**Authentication:** Bearer JWT (issued via `POST /auth/login`) or API key starting with `tgk_` (machine-to-machine).\n\n**Sandbox:** Same endpoints at `https://api-sandbox.tonegrid.pro/api`. Separate DB + JWT secret. No real DSP pushes.\n\n**Status:** https://api-docs.tonegrid.pro/status", "contact": { "name": "ToneGrid Support", "email": "support@tonegrid.pro", "url": "https://support.tonegrid.pro" }, "license": { "name": "Proprietary", "url": "https://tonegrid.pro/terms" } }, "servers": [ { "url": "https://api.tonegrid.pro", "description": "Production" }, { "url": "https://api-sandbox.tonegrid.pro/api", "description": "Sandbox" } ], "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "tags": [ { "name": "Authentication", "description": "Bearer JWT + tgk_ API key flows" }, { "name": "Releases", "description": "Release lifecycle: create, submit, approve, distribute" }, { "name": "Tracks", "description": "Track CRUD + audio upload + extended track properties + Atmos" }, { "name": "Artists", "description": "Artist roster" }, { "name": "Webhooks", "description": "HMAC-signed events. Per-DSP event names reinforce direct delivery." }, { "name": "Ingestion", "description": "Push releases via REST JSON / DDEX XML / CSV / JSON bulk / SFTP" }, { "name": "Supply Chain", "description": "Monetization, pricing, territories, DSP matrix, delivery plan, effective config, per-DSP overrides" }, { "name": "Rights", "description": "Usage rights + copyright + mech license + AI disclosure" }, { "name": "DDEX", "description": "Preview the literal DDEX ERN 4.3 XML and queue delivery per DSP" }, { "name": "Animated Artwork", "description": "Apple Motion Artwork + Spotify Canvas" }, { "name": "Finance", "description": "Periods, sales reports, statements, payouts, balance" }, { "name": "Credits", "description": "Writers + Publishers + Track collaborators (composition side of the DDEX bundle)" }, { "name": "Localizations", "description": "Multi-language titles, descriptions, lyrics — BCP-47 locales emitted into DDEX per-locale Title blocks" }, { "name": "Tenants", "description": "Parent / child hierarchy + login-as impersonation" }, { "name": "Status", "description": "Public health probes (no auth). Safe for load balancers and uptime monitors." } ], "paths": { "/health": { "get": { "tags": [ "Status" ], "summary": "Public health probe (no auth)", "description": "Returns HTTP 200 when the API process is alive and the database is reachable. Returns HTTP 503 if the DB ping fails. No auth, no rate-limit. Cheap (< 5 ms typical). Safe to poll at 1 Hz from anywhere — used by api-docs.tonegrid.pro/status, by external uptime monitors, and by load balancers.", "responses": { "200": { "description": "Process + DB are healthy. JSON body includes status, time (ISO 8601 UTC), environment, version, and a checks.db block with ok/duration_ms/error." }, "503": { "description": "Process alive but DB ping failed. JSON body includes the same shape with checks.db.ok = false and checks.db.error populated." } } } }, "/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Login with tenant credentials", "requestBody": { "required": true, "content": { "application/json": { "example": { "email": "you@example.com", "password": "s3cr3t", "tenant_slug": "lagos-records" } } } }, "responses": { "200": { "description": "Access + refresh tokens", "content": { "application/json": { "example": { "success": true, "data": { "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_at": "2026-05-18T12:00:00Z" } } } } }, "404": { "description": "Tenant not found" }, "422": { "description": "Validation failed" } } } }, "/auth/token/refresh": { "post": { "tags": [ "Authentication" ], "summary": "Rotate refresh token", "responses": { "200": { "description": "New access token" } } } }, "/auth/token/revoke": { "post": { "tags": [ "Authentication" ], "summary": "Revoke a refresh token", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "204": { "description": "Revoked" } } } }, "/releases": { "get": { "tags": [ "Releases" ], "summary": "List releases", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size 1-100", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list" } } }, "post": { "tags": [ "Releases" ], "summary": "Create draft release", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Midnight in Lagos", "type": "ep", "genre": "Afrobeats", "release_date": "2026-07-12", "upc": "0123456789012" } } } }, "responses": { "201": { "description": "Created" }, "422": { "description": "Validation failed" } } } }, "/releases/{uuid}": { "get": { "tags": [ "Releases" ], "summary": "Get release", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Release detail" } } }, "patch": { "tags": [ "Releases" ], "summary": "Update release", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Releases" ], "summary": "Soft-delete release", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/releases/{uuid}/submit": { "post": { "tags": [ "Releases" ], "summary": "Submit release for review", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Submitted" } } } }, "/releases/{uuid}/tracks": { "get": { "tags": [ "Tracks" ], "summary": "List tracks of a release", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Track array" } } }, "post": { "tags": [ "Tracks" ], "summary": "Add track to release", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Opening", "track_number": 1, "isrc": "USRC12345678", "duration_seconds": 215 } } } }, "responses": { "201": { "description": "Created" } } } }, "/tracks/{uuid}": { "get": { "tags": [ "Tracks" ], "summary": "Get track", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Track detail" } } }, "patch": { "tags": [ "Tracks" ], "summary": "Update track (incl. track_properties, version_type, audio specs, Dolby Atmos)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Opening", "version_type": "remix", "lyric_format": "lrc", "track_properties": [ "remix", "includes_ai" ], "audio_format": "wav", "audio_sample_rate_hz": 96000, "audio_bit_depth": 24, "audio_channels": 2, "audio_lufs": -14, "dolby_isrc": "USRC12345699", "album_only": false } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Tracks" ], "summary": "Soft-delete track", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/tracks/{uuid}/upload": { "post": { "tags": [ "Tracks" ], "summary": "Upload master audio (multipart `audio`)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "audio": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Stored" } } } }, "/artists": { "get": { "tags": [ "Artists" ], "summary": "List artists", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Artists" ], "summary": "Create artist", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Wizkid", "slug": "wizkid" } } } }, "responses": { "201": { "description": "Created" } } } }, "/artists/{uuid}": { "get": { "tags": [ "Artists" ], "summary": "Get artist", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Artist UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "Artists" ], "summary": "Update artist", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Artist UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "Artists" ], "summary": "Soft-delete artist", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Artist UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List subscriptions", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Paginated" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create subscription (raw secret returned ONCE)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Production hook", "url": "https://example.com/tg/webhook", "events": [ "release.dsp.*.live", "ingestion.*" ], "description": "Backend notifier" } } } }, "responses": { "201": { "description": "Created — raw secret in response" }, "409": { "description": "Limit (25) reached" } } } }, "/webhooks/event-types": { "get": { "tags": [ "Webhooks" ], "summary": "Canonical event catalogue + wildcard patterns", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Events array" } } } }, "/webhooks/{uuid}": { "get": { "tags": [ "Webhooks" ], "summary": "Show subscription", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Webhook UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Webhook UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Soft-delete", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Webhook UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/webhooks/{uuid}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Trigger webhook.test event", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Webhook UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Delivered" } } } }, "/webhooks/{uuid}/regenerate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate signing secret", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Webhook UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "New raw secret returned" } } } }, "/webhooks/{uuid}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Per-attempt delivery log", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Webhook UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Paginated" } } } }, "/ingestion/json": { "post": { "tags": [ "Ingestion" ], "summary": "Real-time JSON ingest — single release with tracks", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Midnight in Lagos", "type": "ep", "genre": "Afrobeats", "release_date": "2026-07-12", "upc": "0123456789012", "tracks": [ { "title": "Opening", "track_number": 1, "isrc": "USRC12345678", "duration_seconds": 215 } ] } } } }, "responses": { "201": { "description": "Created" }, "422": { "description": "Validation failed" } } } }, "/ingestion/bulk": { "post": { "tags": [ "Ingestion" ], "summary": "Async bulk JSON (max 200)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "202": { "description": "Queued" } } } }, "/ingestion/ddex": { "post": { "tags": [ "Ingestion" ], "summary": "DDEX ERN 3.8.2 / 4.3 XML upload (raw body OR multipart `ddex_xml`)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string", "example": "..." } } } }, "responses": { "202": { "description": "Queued with ingestion_job_id" } } } }, "/ingestion/csv": { "post": { "tags": [ "Ingestion" ], "summary": "CSV bulk import (multipart `releases_csv`)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "202": { "description": "Queued" } } } }, "/ingestion/jobs": { "get": { "tags": [ "Ingestion" ], "summary": "List ingestion jobs", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "description": "Filter by channel", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Filter by state", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "ISO date", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "ISO date", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated" } } } }, "/ingestion/jobs/{uuid}": { "get": { "tags": [ "Ingestion" ], "summary": "Job detail (state, files, validation errors, release_id)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Job UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } }, "/supply-chain/monetization-policies": { "get": { "tags": [ "Supply Chain" ], "summary": "Monetization policy catalogue", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } } }, "/supply-chain/pricing-tiers": { "get": { "tags": [ "Supply Chain" ], "summary": "Pricing tier catalogue", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } } }, "/supply-chain/dsps": { "get": { "tags": [ "Supply Chain" ], "summary": "DSP matrix — direct DDEX delivery method, ERN version, certification level per DSP", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } } }, "/supply-chain/territories": { "get": { "tags": [ "Supply Chain" ], "summary": "Territory catalogue (ISO 3166-1)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } } }, "/supply-chain/releases/{uuid}": { "get": { "tags": [ "Supply Chain" ], "summary": "Read release config", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } }, "/supply-chain/releases/{uuid}/monetization": { "put": { "tags": [ "Supply Chain" ], "summary": "Set monetization policies", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "monetization_policy_codes": [ "subscription_streaming", "permanent_download" ] } } } }, "responses": { "200": { "description": "OK" } } } }, "/supply-chain/releases/{uuid}/pricing-tier": { "put": { "tags": [ "Supply Chain" ], "summary": "Set pricing tier", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "pricing_tier_code": "front_line" } } } }, "responses": { "200": { "description": "OK" } } } }, "/supply-chain/releases/{uuid}/territories": { "put": { "tags": [ "Supply Chain" ], "summary": "Set territory clearances", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "territory_mode": "include", "territory_codes": [ "NG", "GH", "KE", "ZA" ] } } } }, "responses": { "200": { "description": "OK" } } } }, "/supply-chain/releases/{uuid}/delivery-plan": { "get": { "tags": [ "Supply Chain" ], "summary": "Per-DSP delivery plan (proof endpoint)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } }, "/supply-chain/releases/{uuid}/effective-config": { "get": { "tags": [ "Supply Chain" ], "summary": "Resolved per-DSP final state (what each DDEX bundle gets)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } }, "/supply-chain/releases/{uuid}/dsps/{slug}/overrides": { "get": { "tags": [ "Supply Chain" ], "summary": "Read per-DSP override", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "slug", "in": "path", "required": true, "description": "DSP slug", "schema": { "type": "string", "example": "spotify" } } ], "responses": { "200": { "description": "OK" } } }, "put": { "tags": [ "Supply Chain" ], "summary": "Write per-DSP override", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "slug", "in": "path", "required": true, "description": "DSP slug", "schema": { "type": "string", "example": "spotify" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "pricing_tier_code": "premium", "territory_mode": "exclude", "territory_codes": [ "CN" ], "is_blocked": false } } } }, "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "Supply Chain" ], "summary": "Clear per-DSP override (re-inherit release-level config)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "slug", "in": "path", "required": true, "description": "DSP slug", "schema": { "type": "string", "example": "spotify" } } ], "responses": { "204": { "description": "Cleared" } } } }, "/releases/{uuid}/rights": { "get": { "tags": [ "Rights" ], "summary": "Read release rights envelope", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "put": { "tags": [ "Rights" ], "summary": "Update rights (streaming/download/ugc/sync, P-line, C-line, ISWC, IPI, PRO, mech, AI disclosure)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "streaming": true, "download": true, "ugc": true, "sync": false, "p_line": "(P) 2026 Lagos Sound Recordings", "c_line": "(C) 2026 Lagos Sound Recordings", "copyright_year": 2026, "mech_license_held": true, "mech_license_provider": "MLC", "iswc": "T-123456789-0", "ai_disclosure": "none" } } } }, "responses": { "200": { "description": "OK" } } } }, "/releases/{uuid}/ddex/preview/{dsp_slug}": { "get": { "tags": [ "DDEX" ], "summary": "Preview DDEX ERN 4.3 NewReleaseMessage for a DSP (.xml suffix for download)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "dsp_slug", "in": "path", "required": true, "description": "DSP slug, optional .xml suffix", "schema": { "type": "string", "example": "spotify" } } ], "responses": { "200": { "description": "JSON envelope w/ XML + sha256" } } } }, "/releases/{uuid}/ddex/validate/{dsp_slug}": { "get": { "tags": [ "DDEX" ], "summary": "XSD-validate the generated DDEX against official ERN 4.3 schema", "description": "Runs the rendered NewReleaseMessage through libxml's schemaValidate against /opt/ddex-schemas/ern43/release-notification.xsd. Returns the XML plus a validation block { valid, errors[], xsd_path, ern_version }. Beyond-standard feature most aggregators don't expose.", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "dsp_slug", "in": "path", "required": true, "description": "DSP slug", "schema": { "type": "string", "example": "spotify" } } ], "responses": { "200": { "description": "Validation report + XML. Check data.validation.valid to know whether the document passes the official XSD." } } } }, "/releases/{uuid}/ddex/deliver": { "post": { "tags": [ "DDEX" ], "summary": "Queue delivery to every attached DSP", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "202": { "description": "Queued" } } } }, "/releases/{uuid}/ddex/deliver/{dsp_slug}": { "post": { "tags": [ "DDEX" ], "summary": "Queue delivery to one DSP", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "dsp_slug", "in": "path", "required": true, "description": "DSP slug", "schema": { "type": "string", "example": "spotify" } } ], "responses": { "202": { "description": "Queued" } } } }, "/releases/{uuid}/ddex/redeliver": { "post": { "tags": [ "DDEX" ], "summary": "Re-deliver as metadata UPDATE to every attached DSP", "description": "Use this when the metadata for an already-delivered release has changed (typo corrections, new contributor, artwork swap). The DDEX worker pushes a fresh NewReleaseMessage to every attached DSP, reusing the original MessageThreadId so the DSP treats it as an update to the prior delivery in the same thread (rather than a new release). Each row's status flips to update_submitted and fires release.dsp..update_submitted webhook; after the worker pushes successfully it fires release.dsp..updated.", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "202": { "description": "Accepted. Per-DSP queue state in data.queued; .update_submitted webhook fires for each DSP" }, "422": { "description": "No DSPs attached to this release. Attach via POST /releases/:uuid/dsps first." } } } }, "/releases/{uuid}/ddex/purge/preview/{dsp_slug}": { "get": { "tags": [ "DDEX" ], "summary": "Preview the PurgeReleaseMessage XML for a hard takedown", "description": "Returns the literal DDEX ERN 4.3 PurgeReleaseMessage that the DDEX worker would push to this DSP if you queued a purge. MessageThreadId reuses the original NewReleaseMessage thread for correlation. Append .xml to download as a raw .xml file. PurgeReleaseMessage is intended for hard removals (corrupt metadata, mandated takedowns) — for normal commercial takedowns, prefer redelivering a NewReleaseMessage whose Deal ValidityPeriod EndDateTime is now.", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "dsp_slug", "in": "path", "required": true, "description": "DSP slug, optional .xml suffix", "schema": { "type": "string", "example": "spotify" } } ], "responses": { "200": { "description": "JSON envelope with XML + sha256 + size_bytes + message_type=PurgeReleaseMessage. With .xml suffix, returns raw XML download." } } } }, "/releases/{uuid}/ddex/purge/validate/{dsp_slug}": { "get": { "tags": [ "DDEX" ], "summary": "XSD-validate the PurgeReleaseMessage against ERN 4.3 schema", "description": "Same as /ddex/validate but for the PurgeReleaseMessage variant. Use in CI before queueing a takedown.", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string" } }, { "name": "dsp_slug", "in": "path", "required": true, "description": "DSP slug", "schema": { "type": "string", "example": "spotify" } } ], "responses": { "200": { "description": "Validation report. Check data.validation.valid." } } } }, "/releases/{uuid}/ddex/purge": { "post": { "tags": [ "DDEX" ], "summary": "Queue PurgeReleaseMessage delivery to every attached DSP", "description": "Hard takedown. Flips every release_dsp_delivery row to status=takedown_submitted and fires release.dsp..takedown_submitted webhook. The DDEX worker then renders + pushes the PurgeReleaseMessage; on success the row goes to status=taken_down and release.dsp..taken_down fires.", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted. Per-DSP queue state in data.queued." }, "422": { "description": "No DSPs attached to this release. Nothing to purge." } } } }, "/releases/{uuid}/ddex/purge/{dsp_slug}": { "post": { "tags": [ "DDEX" ], "summary": "Queue PurgeReleaseMessage delivery to one DSP", "description": "Per-DSP variant of the purge endpoint. Useful for selective takedowns (e.g. takedown from one DSP while leaving others live).", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string" } }, { "name": "dsp_slug", "in": "path", "required": true, "description": "DSP slug", "schema": { "type": "string", "example": "spotify" } } ], "responses": { "202": { "description": "Accepted. data.dsp + data.state = takedown_submitted." }, "422": { "description": "DSP not attached to this release." } } } }, "/releases/{uuid}/ddex/deliveries": { "get": { "tags": [ "DDEX" ], "summary": "Per-DSP delivery status", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Status array" } } } }, "/releases/{uuid}/animated-artwork": { "get": { "tags": [ "Animated Artwork" ], "summary": "List animated cover artwork for a release", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } }, "/releases/{uuid}/animated-artwork/{asset_type}": { "get": { "tags": [ "Animated Artwork" ], "summary": "Show one artwork asset", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "asset_type", "in": "path", "required": true, "description": "square_motion | tall_motion | canvas_loop", "schema": { "type": "string", "example": "square_motion" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Animated Artwork" ], "summary": "Upload artwork (multipart `asset` field; MP4/MOV/WebM/GIF, ≤50 MB)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "asset_type", "in": "path", "required": true, "description": "square_motion | tall_motion | canvas_loop", "schema": { "type": "string", "example": "square_motion" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Stored" } } }, "delete": { "tags": [ "Animated Artwork" ], "summary": "Soft-delete artwork", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "asset_type", "in": "path", "required": true, "description": "square_motion | tall_motion | canvas_loop", "schema": { "type": "string", "example": "square_motion" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/finance/balance": { "get": { "tags": [ "Finance" ], "summary": "Tenant balance summary", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } } }, "/finance/periods": { "get": { "tags": [ "Finance" ], "summary": "List accounting periods", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Finance" ], "summary": "Create period", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "2026-04", "period_type": "month", "start_date": "2026-04-01", "end_date": "2026-04-30" } } } }, "responses": { "201": { "description": "Created" } } } }, "/finance/periods/{code}": { "get": { "tags": [ "Finance" ], "summary": "Show period", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Period code", "schema": { "type": "string", "example": "2026-04" } } ], "responses": { "200": { "description": "OK" } } } }, "/finance/sales-reports": { "get": { "tags": [ "Finance" ], "summary": "Raw sales reports (per period × DSP × release × track × country)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Period code", "schema": { "type": "string" } }, { "name": "dsp", "in": "query", "required": false, "description": "DSP slug", "schema": { "type": "string" } }, { "name": "release", "in": "query", "required": false, "description": "Release UUID", "schema": { "type": "string" } }, { "name": "track", "in": "query", "required": false, "description": "Track UUID", "schema": { "type": "string" } }, { "name": "isrc", "in": "query", "required": false, "description": "ISRC", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO alpha-2", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated with aggregates" } } } }, "/finance/statements": { "get": { "tags": [ "Finance" ], "summary": "List tenant statements", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } } }, "/finance/statements/{invoice}": { "get": { "tags": [ "Finance" ], "summary": "Show statement", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "Invoice number", "schema": { "type": "string", "example": "INV-2026-04-001" } } ], "responses": { "200": { "description": "OK" } } } }, "/finance/statements/{invoice}.csv": { "get": { "tags": [ "Finance" ], "summary": "Download statement CSV", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "Invoice number", "schema": { "type": "string", "example": "INV-2026-04-001" } } ], "responses": { "200": { "description": "text/csv", "content": { "text/csv": {} } } } } }, "/finance/statements/{invoice}/approve": { "post": { "tags": [ "Finance" ], "summary": "Approve statement", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "Invoice number", "schema": { "type": "string", "example": "INV-2026-04-001" } } ], "responses": { "200": { "description": "Approved" } } } }, "/finance/payee-statements": { "get": { "tags": [ "Finance" ], "summary": "Per-payee statements", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Paginated" } } } }, "/finance/payee-statements/{uuid}": { "get": { "tags": [ "Finance" ], "summary": "Show payee statement", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Payee statement UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } }, "/finance/payee-statements/{uuid}/approve": { "post": { "tags": [ "Finance" ], "summary": "Approve payee statement", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Payee statement UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Approved" } } } }, "/finance/payouts": { "get": { "tags": [ "Finance" ], "summary": "List payouts", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } } }, "/finance/payouts/{uuid}": { "get": { "tags": [ "Finance" ], "summary": "Show payout", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Payout UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } }, "/writers": { "get": { "tags": [ "Credits" ], "summary": "List writers", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Credits" ], "summary": "Create writer", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Ayodeji Balogun", "iswc": "T-123456789-0", "ipi_name_number": "123456789", "pro_affiliation": "PRS", "country": "NG" } } } }, "responses": { "201": { "description": "Created" } } } }, "/writers/{uuid}": { "get": { "tags": [ "Credits" ], "summary": "Show writer", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Writer UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "Credits" ], "summary": "Update writer", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Writer UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "Credits" ], "summary": "Soft-delete writer", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Writer UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/publishers": { "get": { "tags": [ "Credits" ], "summary": "List publishers", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Credits" ], "summary": "Create publisher", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Lagos Sound Publishing", "ipi_name_number": "987654321", "pro_affiliation": "ASCAP", "country": "NG", "is_controlled": true, "mech_license_via": "MLC" } } } }, "responses": { "201": { "description": "Created" } } } }, "/publishers/{uuid}": { "get": { "tags": [ "Credits" ], "summary": "Show publisher", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Publisher UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "Credits" ], "summary": "Update publisher", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Publisher UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "Credits" ], "summary": "Soft-delete publisher", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Publisher UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/tracks/{uuid}/writers": { "get": { "tags": [ "Credits" ], "summary": "Read track writers", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "put": { "tags": [ "Credits" ], "summary": "Set track writers (full replace, shares must sum to 100)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "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 } ] } } } }, "responses": { "200": { "description": "OK" } } } }, "/tracks/{uuid}/publishers": { "get": { "tags": [ "Credits" ], "summary": "Read track publishers", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "put": { "tags": [ "Credits" ], "summary": "Set track publishers (per-writer, per-territory shares)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "publishers": [ { "publisher_uuid": "...", "for_writer_uuid": "...", "share_percent": 100, "is_administrator": true, "territory_codes": [ "NG", "GH", "KE" ] } ] } } } }, "responses": { "200": { "description": "OK" } } } }, "/tracks/{uuid}/collaborators": { "get": { "tags": [ "Credits" ], "summary": "Read track collaborators", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "put": { "tags": [ "Credits" ], "summary": "Set track collaborators (full replace, 27-role enum)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "collaborators": [ { "name": "Sarz", "role": "producer", "credit_order": 1 }, { "name": "Tems", "role": "featured_artist", "credit_order": 2 } ] } } } }, "responses": { "200": { "description": "OK" } } } }, "/releases/{uuid}/localizations": { "get": { "tags": [ "Localizations" ], "summary": "Read release localizations (titles + descriptions + preferred_locale)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "put": { "tags": [ "Localizations" ], "summary": "Replace release localizations (BCP-47 keys: en, en-US, fr, ja, yo, ig, ha, sw, zh-CN, ar …)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Release UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "preferred_locale": "en", "localized_titles": { "en": "Midnight in Lagos", "fr": "Minuit à Lagos", "yo": "Òjò Òru Èkó", "ja": "ラゴスの真夜中" }, "localized_descriptions": { "en": "Late-night Afrobeats EP.", "fr": "EP afrobeats nocturne." } } } } }, "responses": { "200": { "description": "OK" } } } }, "/tracks/{uuid}/localizations": { "get": { "tags": [ "Localizations" ], "summary": "Read track localizations (titles + title_versions + lyrics per locale)", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } }, "put": { "tags": [ "Localizations" ], "summary": "Replace track localizations", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Track UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "localized_titles": { "en": "Opening", "fr": "Ouverture" }, "localized_title_versions": { "en": "Album Mix" }, "localized_lyrics": { "en": "[Verse 1]…", "fr": "[Couplet 1]…" } } } } }, "responses": { "200": { "description": "OK" } } } }, "/tenants/clients": { "get": { "tags": [ "Tenants" ], "summary": "List child tenants", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Tenants" ], "summary": "Onboard child tenant", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Distro80 Records", "slug": "distro80", "tenant_role": "client" } } } }, "responses": { "201": { "description": "Created" } } } }, "/tenants/clients/{uuid}": { "get": { "tags": [ "Tenants" ], "summary": "Show child detail", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Child tenant UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } }, "/tenants/clients/{uuid}/login-as": { "post": { "tags": [ "Tenants" ], "summary": "Mint impersonation JWT", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Child tenant UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Token with on_behalf_of claim" } } } }, "/tenants/clients/{uuid}/usage": { "get": { "tags": [ "Tenants" ], "summary": "Usage rollup", "security": [ { "BearerJWT": [] }, { "ApiKey": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Child tenant UUID", "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "BearerJWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Browser / mobile session token issued by POST /auth/login. Short-lived (15 min default)." }, "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "tgk_", "description": "Machine-to-machine key (starts with `tgk_`). Mint from Dashboard → API Keys. Carries fine-grained scopes." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotent retry. SHA-256(tenant_id||key) scope, body-hash gate, 24h TTL. Replay returns the stored response with `X-ToneGrid-Idempotent-Replay: true` header.", "schema": { "type": "string", "maxLength": 255 } }, "XRequestId": { "name": "X-Request-Id", "in": "header", "required": false, "description": "Propagated through audit_log + worker logs for tracing. If omitted, a UUID v4 is generated server-side.", "schema": { "type": "string", "maxLength": 36 } } } }, "externalDocs": { "url": "https://api-docs.tonegrid.pro", "description": "Human-readable docs with full examples, sandbox onboarding, webhook event catalogue, errors catalogue." } }