Supply Chain — Catalog & Distribution API

Introduction

This documentation describes the InterSpace Distribution API endpoints and JSON models used to operate a distribution supply chain: releases, tracks, artists, asset uploads, deliveries, and webhooks. Use these endpoints to build a full distribution UI in your app.

Base URLs

Use the Production base URL above for v1 endpoints. To request a sandbox account (recommended for ingestion and delivery testing), email devs@interspacemusic.com.

Authentication & Headers

Authorization Header

Example header:

Authorization: Bearer <access_token>

Content Type

All request bodies are application/json unless otherwise noted (multipart for uploads).

Implementation Models

We recommend the Child Account model for most partners — create a child tenant per end-user and perform content actions in that child context when required. This allows separation of catalogs and royalty ownership per artist/label.

API Reference — Releases

This section documents all Release endpoints in full detail. Each endpoint includes:
• What the endpoint does
• When and why to use it
• Required headers and parameters
• Detailed request body examples
• Success & error response examples

What it does: Registers a new release (Single / EP / Album) and returns basic metadata. This must be called before adding tracks for the release.

When to use

• When a partner or dashboard needs to create a new release record
• When onboarding a project from another platform

Required Headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Required fields

• releaseTitle, releasePhoto
• releaseType, releaseDate
• yearOfCopyright, copyrightHolder
• language, genre
• labelId, labelName
• primaryArtistName, primaryArtistId
• albumCopyright[], distroStores[]
• userId, userEmail

Optional fields

• releaseVersion, pastReleaseDate
• remixer, smartLink
• distroSpeedType, upcCode
• subGenre, otherArtist[], otherArtistRole[]

Request body example

{
  "releaseTitle": "No Balance",
  "releasePhoto": "https://cdn.example.com/covers/no-balance.jpg",
  "releaseVersion": "Deluxe",
  "releaseType": "Single",
  "pastReleaseDate": "2025-01-20T00:00:00.000Z",
  "releaseDate": "2025-02-10T12:00:00.000Z",
  "yearOfCopyright": "2025",
  "copyrightHolder": "EpiBlaq Entertainment",
  "language": "English",
  "distroSpeedType": "Express",
  "upcCode": "123456789012",
  "genre": "Afrobeats",
  "subGenre": "Afro-fusion",
  "labelId": "label_83473",
  "labelName": "EpiBlaq Records",
  "primaryArtistName": "EpiBlaq",
  "primaryArtistId": "artist_00293",
  "otherArtist": ["Burna Boy", "Omah Lay"],
  "otherArtistRole": ["Featured Artist", "Producer"],
  "albumCopyright": ["© 2025 EpiBlaq Records"],
  "distroStores": ["Spotify", "Apple Music"],
  "userId": "user_2290",
  "userEmail": "user@example.com"
}

Success response (201)

{
  "success": true,
  "message": "Release created successfully",
  "data": {
    "id": "f39e1c0a-...",
    "albumSlug": "no-balance-deluxe-user-example-12ab3c",
    "status": "Pending",
    "createdAt": "2025-11-22T10:00:00Z"
  }
}

Error response examples

// Missing API key
{
  "success": false,
  "message": "Missing API key",
  "data": null
}

// Validation failure (missing required field)
{
  "success": false,
  "message": ["releaseDate should not be empty", "yearOfCopyright should not be empty"],
  "data": null
}

What it does: Returns an array of release objects (metadata only). Use for dashboards and catalog listings. Tracks are not included by default.

Required headers

x-api-key: YOUR_API_KEY

Success response (200)

{
  "success": true,
  "message": "Releases fetched successfully",
  "data": [
    {
      "id": "f39e1c0a-...",
      "releaseTitle": "No Balance",
      "albumSlug": "no-balance-...",
      "status": "Pending",
      "createdAt": "..."
    },
    ...
  ]
}

Error response (401)

{
  "success": false,
  "message": "Invalid API key",
  "data": null
}

Returns full release details including metadata and approval status. Useful when rendering the release detail view in a dashboard.

Path params

id (string) — UUID of the release

Success response (200)

{
  "success": true,
  "message": "Release fetched successfully",
  "data": {
    "id": "f39e1c0a-...",
    "releaseTitle": "No Balance",
    "albumSlug": "no-balance-...",
    "status": "Pending",
    "releaseDate": "2025-02-10T12:00:00.000Z",
    "tracks": [] // not populated by this endpoint by default
  }
}

Error response (404)

{
  "success": false,
  "message": "Release not found",
  "data": null
}

Returns all releases associated to a user ID or account. Useful for user dashboards and management screens.

Path params

id (string) — user id provided by the partner

Success Response (200)

{
  "success": true,
  "message": "User releases fetched",
  "data": [
    { "id": "...", "albumSlug":"...", "releaseTitle":"..." }
  ]
}

Partially updates the release. Only include fields you want to change (Partial update). The server will ignore missing fields.

Request body example (update genre & distroStores)

{
  "genre": "Afrobeats",
  "distroStores": ["Spotify", "Apple Music", "Boomplay"]
}

Success response (200)

{
  "success": true,
  "message": "Release updated successfully",
  "data": { "id":"...", "genre":"Afrobeats", "...": "..." }
}

Error response (400 / 404)

{
  "success": false,
  "message": "Invalid request or release not found",
  "data": null
}

Removes a release and cascades delete to all associated tracks (CASCADE). Use carefully — this is destructive.

Success (200)

{
  "success": true,
  "message": "Release deleted successfully",
  "data": null
}

Error (404)

{
  "success": false,
  "message": "Release not found",
  "data": null
}

Release Status Endpoints

These endpoints change the release status. Only moderator or automated workflows should call them. Approve sets approvedAt.

{
  "success": true,
  "message": "Release approved",
  "data": {
    "id": "...",
    "status": "Approved",
    "approvedAt": "2025-11-22T10:15:00Z"
  }
}

{
  "success": true,
  "message": "Release rejected",
  "data": {
    "id": "...",
    "status": "Rejected"
  }
}

{
  "success": true,
  "message": "Release taken down",
  "data": {
    "id": "...",
    "status": "Taken Down"
  }
}

Track API

Create and manage tracks belonging to releases. Each endpoint below includes purpose, headers, request & response examples, and notes.

Creates a new track and associates it with an existing release. The release must exist before you create a track (use /v1/release).

Required headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Required fields

• trackTitle, language, lyrics
• primaryArtistName, primaryArtistId
• writer[], collaboratorName[], collaboratorRole[]
• trackAudio, releaseId, userId, userEmail

Optional fields

• trackVersion, pastReleaseDate, otherArtist[], otherArtistRole[], isrcCode

Request body example

{
  "trackTitle": "No Balance",
  "trackVersion": "Acoustic",
  "language": "English",
  "explicitContent": false,
  "previewStartMin": "00",
  "previewStartSec": "30",
  "pastReleaseDate": "2024-09-15T00:00:00.000Z",
  "lyrics": "Girl your love no get balance...",
  "primaryArtistName": "EpiBlaq",
  "primaryArtistId": "artist_00293",
  "otherArtist": ["Burna Boy"],
  "otherArtistRole": ["Featured Artist"],
  "writer": ["EpiBlaq"],
  "collaboratorName": ["Telz"],
  "collaboratorRole": ["Producer"],
  "isrcCode": "QZABC1234567",
  "trackAudio": "https://cdn.example.com/audio/no-balance.mp3",
  "releaseId": "f39e1c0a-...",
  "userId": "user_2290",
  "userEmail": "user@example.com"
}

Success response (201)

{
  "success": true,
  "message": "Track created successfully",
  "data": {
    "id": "a12b3c4d-...",
    "trackSlug": "no-balance-acoustic-user-example-3c2f1a",
    "createdAt": "2025-11-22T11:00:00Z"
  }
}

Error example (400 / 404)

{
  "success": false,
  "message": "Release not found",
  "data": null
}

Returns all tracks. Use query/filtering on the client side (or implement server-side filters later) to tailor results.

Success (200)

{
  "success": true,
  "message": "Tracks fetched successfully",
  "data": [
    { "id":"...", "trackTitle":"...", "trackSlug":"...", "releaseId":"..." }
  ]
}

Returns full track metadata including relations like release id and artist info.

Success (200)

{
  "success": true,
  "message": "Track fetched successfully",
  "data": {
    "id":"a12b3c4d-...",
    "trackTitle":"No Balance",
    "trackSlug":"no-balance-...",
    "releaseId":"f39e1c0a-...",
    "primaryArtistName":"EpiBlaq"
  }
}

Error (404)

{
  "success": false,
  "message": "Track not found",
  "data": null
}

List of tracks that belong to a release (by release UUID).

Success (200)

{
  "success": true,
  "message": "Tracks fetched for release",
  "data": [{ "id":"...", "trackTitle":"...", "trackSlug":"..." }]
}

Tracks created by a specific user ID.

Success (200)

{
  "success": true,
  "message": "User tracks fetched",
  "data": [{ "id":"...", "trackTitle":"..." }]
}

Partial update — include only fields you want to change (e.g., lyrics, preview times, explicit flag).

Request body sample

{
  "lyrics": "Updated lyrics...",
  "explicitContent": true
}

Success (200)

{
  "success": true,
  "message": "Track updated successfully",
  "data": { "id":"...", "lyrics":"Updated lyrics..." }
}

Error (400 / 404)

{
  "success": false,
  "message": "Invalid data or track not found",
  "data": null
}

Deletes track permanently. Use with caution.

Success (200)

{
  "success": true,
  "message": "Track deleted successfully",
  "data": null
}

Error (404)

{
  "success": false,
  "message": "Track not found",
  "data": null
}

Artist API

Create and manage artist entities used as primary artists or contributors.

Request

{
  "name": "Ama Beats",
  "country": "NG",
  "primaryGenre": "Afrobeats",
  "profileImage": "https://cdn.example.com/ama.jpg",
  "externalIds": { "spotify": "spotify:artist:xyz" }
}

Response (201): returns artist object with artistId.

Distribution / Delivery API

Endpoints to submit releases to DSPs, check status, and manage redeliveries/takedowns.

Request

{
  "releaseId": "rel_01Habc",
  "destinations": ["spotify","apple_music","youtube_music"],
  "scheduledDate": "2025-12-01T00:00:00Z",
  "notes": "Priority release"
}

Response (202): returns delivery job id and initial status.

{
  "deliveryJobId":"deljob_01Habc",
  "status":"queued",
  "submittedAt":"2025-11-19T15:00:00Z"
}

{
  "releaseId":"rel_01Habc",
  "deliveries":[
    { "provider":"spotify","status":"accepted","deliveredAt":"2025-11-25T12:00:00Z" },
    { "provider":"apple_music","status":"processing" }
  ]
}

Asset Uploads (Audio & Art)

Audio and artwork uploads use multipart/form-data endpoints; returned object includes fileId or assetId used in release/track creation.

Response returns asset id and CDN url.

{
  "assetId":"file_abc123",
  "url":"https://cdn.interspacemusic.com/files/file_abc123.mp3",
  "type":"audio"
}

curl -X POST "https://api-v1.interspacemusic.com/v1/files" \
  -H "Authorization: Bearer <PARTNER_API_KEY>" \
  -F "file=@./song.mp3" \
  -F "metadata={\"type\":\"audio\",\"title\":\"My Single\"}"

Webhooks

Webhooks notify your system of delivery updates, royalty credits, and asset processing events. Configure webhook URL in your tenant settings.

Events

• delivery.update — { deliveryJobId, releaseId, provider, status }
• asset.processed — { assetId, status, durationMs }
• royalty.credited — { payoutId, amount, currency }

Sample webhook payload

{
  "event":"delivery.update",
  "data":{
    "deliveryJobId":"deljob_01Habc",
    "releaseId":"rel_01Habc",
    "provider":"spotify",
    "status":"accepted",
    "timestamp":"2025-11-25T12:00:00Z"
  }
}

Models

Canonical models for Release, Track, Artist, Delivery job and File asset.

Release (canonical)

{
  "id":"string",
  "releaseTitle":"string",
  "releaseType":"single|album|ep",
  "releaseDate":"YYYY-MM-DD",
  "upcCode":"string",
  "labelId":"string",
  "primaryArtistName":"string",
  "tracks":[ /* array of track objects or track ids */ ],
  "status":"draft|pending|delivered|rejected",
  "smartLink":"string"
}

Track (canonical)

{
  "id":"string",
  "title":"string",
  "isrc":"string",
  "audioAssetId":"string",
  "durationMs":123000,
  "contributors":[ { "artistId":"string","name":"string","role":"primary|featured" } ]
}

Artist (canonical)

{
  "artistId":"string",
  "name":"string",
  "country":"string",
  "primaryGenre":"string",
  "profileImage":"https://..."
}

Delivery job (canonical)

{
  "deliveryJobId":"string",
  "releaseId":"string",
  "destinations":[ "spotify","apple_music" ],
  "status":"queued|processing|completed|failed",
  "submittedAt":"ISO datetime"
}

Notes & Best Practices

• Create artists before creating tracks/releases — avoids duplicates in bulk ingestion.
• Validate UPC and ISRC formats client-side to reduce validation errors server-side.
• Use sandbox accounts for heavy ingestion tests and repeated deliveries.
• Keep Partner API keys on server; use short-lived user tokens for frontend flows.
• When updating released audio or metadata, use /delivery/redeliver for DSPs that support updates.
• Monitor webhooks for delivery updates and reconcile with provider statuses.

InterSpace accepts music releases via SFTP using the DDEX ERN (Electronic Release Notification) standard — the same format used by major distributors worldwide. This guide explains everything a label or rights-holder needs to know to deliver music to InterSpace for distribution to DSPs (Spotify, Apple Music, YouTube Music, etc.).

How it works — step by step

1. You receive your SFTP credentials from InterSpace (host, username, password)
2. You connect to our SFTP server using FileZilla or any SFTP client
3. You upload your release as a folder inside /incoming/
4. Our system automatically detects the upload within 5 minutes
5. It validates your DDEX XML, audio files and artwork
6. You receive a confirmation email (or an error email if something needs fixing)
7. InterSpace reviews and QC-checks your delivery
8. You receive a final approval or rejection email with details
9. On approval, InterSpace pushes your release to the agreed DSPs

Connecting via SFTP

InterSpace will email you your credentials when your account is set up. Here is how to connect using the most popular SFTP clients.

Connection details

Using FileZilla (recommended for beginners)

1. Download FileZilla from filezilla-project.org (free)
2. Open FileZilla → click File → Site Manager
3. Click New Site and enter a name like "InterSpace Delivery"
4. Set Protocol to SFTP – SSH File Transfer Protocol
5. Host: sftp.interspacemusic.com  |  Port: 22
6. Logon Type: Normal → enter your username and password
7. Click Connect
8. Navigate to the /incoming/ folder on the right side
9. Drag your release folder from your computer into /incoming/

Using command line (advanced)

# Connect
sftp your_username@sftp.interspacemusic.com

# Navigate to incoming folder
sftp> cd incoming

# Create a folder for your release
sftp> mkdir ArtistName_AlbumTitle_UPC_20260323

# Upload files
sftp> cd ArtistName_AlbumTitle_UPC_20260323
sftp> put metadata.xml
sftp> put *.wav
sftp> put artwork.jpg

# Done — type exit to close
sftp> exit

Package Structure

Each release you upload must be a folder containing exactly three types of files: a DDEX XML metadata file, your audio files, and your cover artwork. The folder name should be descriptive and unique.

Required folder structure

incoming/
  └── ArtistName_AlbumTitle_UPC_YYYYMMDD/    ← your release folder
        ├── metadata.xml                      ← DDEX ERN XML (required)
        ├── 01_TrackTitle.wav                 ← audio track 1 (WAV or FLAC)
        ├── 02_TrackTitle.wav                 ← audio track 2
        ├── 03_TrackTitle.wav                 ← audio track 3 ...
        └── artwork.jpg                       ← cover art (3000×3000 min)

Naming your release folder

We recommend this naming pattern for your release folder:

ArtistName_AlbumTitle_UPC_ReleaseDate

Example:
Davido_TimelessDeluxe_5034567890123_20260401

File checklist

DDEX XML Metadata Guide

The metadata.xml file tells InterSpace (and eventually the DSPs) everything about your release — artist name, track listing, release date, territories, pricing and more. Most professional DAWs and distribution tools can generate this automatically. Below is a minimal example for a single track release.

Minimal example (single)

<?xml version="1.0" encoding="UTF-8"?>
<NewReleaseMessage
  xmlns="http://ddex.net/xml/ern/382"
  MessageSchemaVersionId="ern/382"
  LanguageAndScriptCode="en">

  <MessageHeader>
    <MessageThreadId>MSG-001</MessageThreadId>
    <MessageId>MSG-001</MessageId>
    <MessageSender>
      <PartyId>YOUR_LABEL_ID</PartyId>
      <PartyName><FullName>Your Label Name</FullName></PartyName>
    </MessageSender>
    <MessageRecipient>
      <PartyId>INTERSPACE</PartyId>
    </MessageRecipient>
    <MessageCreatedDateTime>2026-03-23T10:00:00</MessageCreatedDateTime>
    <MessageControlType>LiveMessage</MessageControlType>
  </MessageHeader>

  <ResourceList>
    <SoundRecording>
      <SoundRecordingType>MusicalWorkSoundRecording</SoundRecordingType>
      <SoundRecordingId>
        <ISRC>GBDUM7620001</ISRC>
      </SoundRecordingId>
      <ResourceReference>A1</ResourceReference>
      <ReferenceTitle>
        <TitleText>My Track Title</TitleText>
      </ReferenceTitle>
      <Duration>PT3M42S</Duration>
      <SoundRecordingDetailsByTerritory>
        <TerritoryCode>Worldwide</TerritoryCode>
        <DisplayArtist>
          <PartyName><FullName>Artist Name</FullName></PartyName>
          <ArtistRole>MainArtist</ArtistRole>
        </DisplayArtist>
        <Genre><GenreText>Afrobeats</GenreText></Genre>
        <ParentalWarningType>NotExplicit</ParentalWarningType>
        <TechnicalSoundRecordingDetails>
          <TechnicalResourceDetailsReference>T1</TechnicalResourceDetailsReference>
          <AudioCodecType>WAV</AudioCodecType>
          <File>
            <URI>01_MyTrackTitle.wav</URI>
          </File>
        </TechnicalSoundRecordingDetails>
      </SoundRecordingDetailsByTerritory>
    </SoundRecording>
  </ResourceList>

  <ReleaseList>
    <Release>
      <ReleaseId>
        <UPC>5034567890123</UPC>
      </ReleaseId>
      <ReleaseReference>R1</ReleaseReference>
      <ReferenceTitle>
        <TitleText>My Album Title</TitleText>
      </ReferenceTitle>
      <ReleaseDate>2026-04-01</ReleaseDate>
      <ReleaseType>Single</ReleaseType>
      <ReleaseResourceReferenceList>
        <ReleaseResourceReference>A1</ReleaseResourceReference>
      </ReleaseResourceReferenceList>
    </Release>
  </ReleaseList>

  <DealList>
    <ReleaseDeal>
      <DealReleaseReference>R1</DealReleaseReference>
      <Deal>
        <DealTerms>
          <CommercialModelType>SubscriptionModel</CommercialModelType>
          <Usage><UseType>OnDemandStream</UseType></Usage>
          <TerritoryCode>Worldwide</TerritoryCode>
          <ValidityPeriod><StartDate>2026-04-01</StartDate></ValidityPeriod>
        </DealTerms>
      </Deal>
    </ReleaseDeal>
  </DealList>

</NewReleaseMessage>

Required XML fields

Artwork Requirements

All DSPs (Spotify, Apple Music, etc.) have strict artwork rules. Your artwork must meet these standards before your release can be approved.

Content rules

• No explicit sexual imagery
• No third-party logos, social media icons or watermarks
• No URLs or website addresses
• Must not be pixelated, blurry or stretched
• Text must be legible at small sizes
• Must not mislead consumers about the artist or content

Audio File Requirements

Your audio files must be high-quality, uncompressed masters. Do not send MP3s — they will be flagged during validation.

Track ordering

We recommend prefixing your audio filenames with their track number for clarity:

01_OpeningTrack.wav
02_SecondTrack.wav
03_ThirdTrack.wav

The filename must exactly match the <URI> value in your DDEX XML — including capitalisation and spaces.

Delivery Status Explained

After you upload a package, you will receive emails at each stage. Here is what each status means:

Frequently Asked Questions

Still have questions? Email us at support@interspacemusic.com or visit our Glossary for definitions of music industry terms.