Your catalog.
Your systems.
One release workflow.

From approved access to your first draft.

1. Get sandbox access. An MDG root administrator creates and approves a partner for an existing account on the sandbox deployment, then issues a scoped key.
2. Verify your identity. Call GET /api/v1/identity and confirm the returned tenant, environment and scopes.
3. Map an artist. Use an existing accessible profile or create one. Label invitations require artist acceptance before their profile becomes available.
4. Create, upload and validate. Create a draft, append tracks, upload artwork and audio, and resolve the validation findings.
5. Submit and track review. Submit through the existing MDG workflow. Recipients complete FAC where required; MDG administrators review the release.

curl "$MDG_BASE_URL/identity" \
  -H "Authorization: Bearer $MDG_API_KEY"

Keys belong on your server.

Send Authorization: Bearer <credential> on every API request. Keys have an environment prefix, scopes and an expiry. They are shown once and stored by MDG as hashes. Do not embed them in browser bundles, mobile apps, URLs, logs or source control.

Administrators approve access, set request/upload limits and approved webhook hostnames, issue keys, revoke keys and suspend accounts at /admin/developer-partners. Rotate by issuing a replacement, testing it, switching your server and revoking the previous key. Reducing approved scopes also reduces what existing keys can do.

Least-privilege scopes

Your API identity never grants administrator access, clearance signing authority or upstream distribution credentials.

Real workflow. Isolated infrastructure.

Sandbox runs the same MDG application and validation services against a dedicated database and B2 bucket. Credentials work only on their matching environment. Test recipients must be allowlisted. Subscriptions, artist consent, agreements, splits and rights checks still apply.

Sandbox rejects store-delivery, live, distributed and takedown transitions. Automatic release publishing is disabled. There is no API endpoint that fabricates FAC acceptance or administrator approval.

Every release follows MDG review.

POST /releases/{id}/submit calls the existing MDG submission service. It checks account entitlements, distribution activation, metadata, artwork, credits and split integrity, then creates any required clearances and queues QC. Submission never approves or distributes the release.

Use GET /releases/{id}/fac to follow clearance progress. Featured artists and producers sign through existing MDG emails and documents. Partners cannot read signing tokens or sign on someone else's behalf. A rejected release is editable only when MDG explicitly enables corrections.

Use release status, canEdit, QC findings and signed events to drive your own application. Treat status values as extensible and display unknown future values safely.

Use MDG's reference data.

Call GET /reference for current genres, DSP IDs, supported languages and upload policies. Do not hardcode catalog mappings. Release creation requires a title, accessible artist ID, release type and your stable externalId. Tracks require a title and track number; validation reports the remaining submission requirements.

ISRC uses the unhyphenated uppercase 12-character format. UPC/EAN accepts 12 or 13 digits; MDG's deterministic QC checks its checksum and catalog conflicts. Existing service-generated identifiers are returned in release metadata. Do not infer or invent identifiers.

Featured credits include performer name, legal name and a valid email for clearance. Track contributors use name and role. Split collaborators require complete identity, positive percentages totalling 100%, and validated ROIDs for external collaborators. Existing invitation/acceptance requirements remain authoritative.

Artwork and audio URLs are output fields. Attach media through upload sessions. Server-controlled status, ownership, approval, clearance and payment fields are rejected as input.

Resumable uploads, checked before storage.

1. Create a session using POST /uploads with release ID, media kind, safe filename, content type, exact byte size and full-file SHA-256. Audio also requires an existing track ID.
2. Split the file into the returned chunkSize. PUT each zero-based part as multipart field file to /uploads/{id}/parts/{part}.
3. Send both the partner key and returned Upload-Token. Retry a part with identical bytes. Changed bytes for an existing part return a conflict.
4. Use GET /uploads/{id} to resume from the received parts. Complete with POST /uploads/{id}/complete and a new idempotency key.

Sessions last one hour. Chunks are at most 2 MiB; the final chunk must match its expected size. Audio is capped at 100 MiB and artwork at 25 MiB, or the lower current MDG policy. Completion validates the full checksum, real media headers, WAV metadata and artwork dimensions, then scans with ClamAV when configured and uses existing B2 storage. The result includes scanStatus; not_configured means no antivirus scan occurred.

Upload tokens are scoped, short-lived capabilities. MDG never returns bucket upload credentials. Abandoned staging chunks expire automatically. Upload reservations count toward your daily quota even when an upload is abandoned.

Verify first. Process once.

Ask MDG to approve your exact receiver hostname, then configure PUT /webhook with an HTTPS URL on port 443. Save its returned signing secret and key ID server-side. Configuring the receiver again rotates the secret. Private IPs, redirects, URL credentials and query strings are rejected.

Verify X-MDG-Signature: v1=<hex> using HMAC-SHA256 over X-MDG-Timestamp + "." + rawRequestBody. Use a constant-time comparison and reject timestamps more than five minutes from your clock. The event body's id matches X-MDG-Event-Id. Persist that ID before applying side effects; duplicate delivery is expected.

Return a 2xx response after durably accepting the event. Delivery workers retry up to 10 times with exponential backoff, jitter and bounded Retry-After handling. Events may arrive out of order; fetch the current release before applying a sensitive state change. Use GET /webhook/deliveries for attempts and POST /webhook/deliveries/{id}/replay for replay. Replays keep the original event ID and use a fresh timestamp and the current signing secret.

// Node.js receiver: body must be the exact received bytes.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, headers, secret) {
  const timestamp = Number(headers['x-mdg-timestamp']);
  if (!Number.isInteger(timestamp) || Math.abs(Date.now()/1000-timestamp) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(String(timestamp) + '.').update(rawBody).digest();
  const value = String(headers['x-mdg-signature'] || '');
  if (!/^v1=[a-f0-9]{64}$/.test(value)) return false;
  return timingSafeEqual(expected, Buffer.from(value.slice(3), 'hex'));
}

Retry the request, not the release.

Every metadata mutation, upload start/completion, submission and webhook change requires an Idempotency-Key: 16–128 letters, digits, dots, colons, underscores or hyphens. Keep one key per logical operation and reuse it for identical retries. MDG stores the result durably, across key rotation and application restarts. Reusing the same key for another route, object or payload returns idempotency_conflict.

Concurrent requests return operation_in_progress. A crashed write or uncertain downstream result returns outcome_unknown; inspect the resource through its ID or external mapping and contact MDG with the request ID. Do not switch keys and blindly submit again. Idempotency records have no automatic expiry.

{ "code": "insufficient_scope", "message": "This credential lacks the required scope.", "requestId": "…" }

Bounded requests. Stable contracts.

Default partner allowance is 60 requests per minute across all its keys. MDG can approve a lower or higher allowance. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset report the partner window; the platform's existing IP protection also applies. Metadata is limited to 64 KiB, lists to 50 items per page, releases to 200 tracks and active upload sessions to 10 per partner.

Use limit and after for cursor pagination; next: null marks the last page. Limits, profile access and catalog ownership are checked on the server.

Version 1 uses /api/v1. Additive response fields and new status values may appear within v1; clients must ignore unknown fields. Breaking changes require another major path and a documented migration period. No v1 endpoint is deprecated in this release.

Working server-side examples.

The downloadable examples use the implemented endpoints and stop at MDG review. Supply your approved base URL, key and current reference IDs. Labels must first complete artist roster acceptance. Audio, artwork and collaborator data must satisfy the actual MDG policies.

curl "$MDG_BASE_URL/releases" \
  -H "Authorization: Bearer $MDG_API_KEY" \
  -H "Idempotency-Key: release-draft-your-unique-id" \
  -H "Content-Type: application/json" \
  --data '{"externalId":"catalog-2026-001","title":"Your Release","artistId":"YOUR_ARTIST_ID","releaseType":"single"}'

A complete brief for your coding agent.

Give this guide and the OpenAPI spec to your integration agent. It includes setup, artist consent, uploads, validation, submission, FAC, webhook verification and recovery constraints.

Implemented endpoints.

These operations are rendered from the same registry that defines server routes and request validation.

Interactive API explorer.

Requests go directly to the selected MDG deployment. The key stays in memory for this page session. Use a scoped sandbox key. Mutations act on real records in that environment.

Choose an operation to inspect or try a request.

Common questions.

v1.0.0

Initial Developer API: approved scoped partner access, existing artist and release workflows, resumable media, deterministic validation, FAC status, signed webhooks, durable retries and generated OpenAPI 3.1. Deployment availability depends on MDG provisioning.