Skip to content

Quickstart

Integrate your platform with the KiTbetter Partner API.

This guide walks approved partners through the basic setup for connecting their website, platform, or internal system to KiTbetter. 

You will issue an API key, authenticate requests, send artist and release metadata, create or connect a KiTbetter for Artists profile, and confirm that a KiTalbum draft has been created successfully.

Step 1 — Issue an API key

Issue an API key in KiTbetter Developer. For the full procedure, see Issue an API key.

Store the key somewhere safe, such as a server environment variable. Never put it in client-side code — see Key management & security.

Step 2 — Authenticate your request

Send the key in the X-API-Key header on every request. All endpoints are served over HTTPS under a single base URL:

https://api.kitbetter.com/partner/v1

A missing or invalid key returns 401, and a key without permission for the endpoint returns 403. For the full header rules, see Authenticate requests.

Step 3 — Send artist and release metadata

Artist and release metadata travel in a single DDEX ERN 3.8.2 XML file — the XML is the source of truth. Upload it to your own storage, then call create an album ingest with a presigned URL to the file. You do not send a separate list of resource URLs: the audio, video, and image files declared inside the XML are downloaded from the URLs it contains.

curl -X POST "https://api.kitbetter.com/partner/v1/ddex/ingests" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 35 \
  -d '{
    "releaseId": "DIST-2026-00123",
    "xmlUrl": "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600"
  }'
  • releaseId is your album identifier. It must be unique per partner — resending the same value returns 409.
  • xmlUrl only needs to be valid at the moment of ingest; KiTbetter immediately copies the file into its own storage.
  • The response can take up to 30 seconds, so set your client timeout to 30 seconds or more.

For the required XML elements (and the recommended ones, such as ISRC and barcode), see create an album ingest.

Step 4 — Create or connect the artist profile

During the ingest, KiTbetter resolves the artist from the XML — the DisplayArtist name and, if present, the ISNI (PartyId).

  • If the artist matches an existing KiTbetter for Artists profile, the album is attached to that profile.
  • If there is no matching profile, a new artist profile is created automatically.
  • If the artist cannot be resolved safely, the ingest is rejected with 422 ARTIST_UNRESOLVED — contact your partner manager to sort out the mapping.

Sending the ISNI along with the artist name noticeably improves matching accuracy, so include it whenever you have one.

Step 5 — Create a KiTalbum draft in KiTbetter for Artists

On success you receive 201 Created: a KiTalbum draft (an album in production) now exists in the artist's KiTbetter for Artists workspace.

{
  "ingestId": "1042",
  "releaseId": "DIST-2026-00123",
  "status": "processing",
  "receivedAt": "2026-08-06T10:38:00+09:00",
  "completedAt": null,
  "resources": { "total": 14, "completed": 0, "failed": 0 }
}
  • Use ingestId as the reference when tracking the ingest or contacting support. Resource files such as audio are loaded asynchronously after the response (status: processing).
  • Sending the same releaseId again returns 409 — an ingested album cannot be modified through the API. See the resend policy.
  • If the response is 4xx or 5xx, check Error codes for the cause and how to respond. A 422 creates nothing, so you can resend after fixing the cause.
  • We recommend logging the requestId returned in error responses, since you will need it when contacting support.

Step 6 — Check processing status

Use the ingestId to check whether the resource files have finished loading.

curl "https://api.kitbetter.com/partner/v1/ddex/ingests/1042" \
  -H "X-API-Key: YOUR_API_KEY"

Once status is completed, the ingest is fully finished. We recommend a first check about 30 seconds after the ingest, then every 30 seconds to 1 minute.

{
  "ingestId": "1042",
  "status": "completed",
  "completedAt": "2026-08-06T10:42:00+09:00",
  "resources": { "total": 14, "completed": 14, "failed": 0 }
}

Instead of polling, you can register a webhook to be notified of completion or failure in real time. Even with webhooks, we recommend keeping this status check as a fallback in case a delivery is missed.

If the status is failed, error.code carries the reason — see ingest failure codes.

Step 7 — Complete the release in KiTbetter for Artists

Once the ingest is completed, the API's job is done. The remaining production steps happen in KiTbetter for Artists, so direct the artist — or an approved partner team member with access to the artist account — to:

  1. Review the imported album, tracks, and resource files.
  2. Finish the album design and production settings.
  3. Submit the album for release review.

The ingested data cannot be changed through the API — corrections after ingest are made in KiTbetter for Artists, or through your partner manager for data-level changes. If your team needs access to an artist account, see Contact & reporting.

Next steps

  • Endpoints reference — full request and response schemas
  • Basics — Base URL, request and response format
  • Code examples — cURL, Python, and JavaScript samples
  • Webhooks — receive ingest completion and failure without polling