Skip to main content

Developer guide

Build publishing into your workflow.

Connect your catalog, submit song information, and track registration progress from your own system. Start with a read-only request to see your songs.

01 / Connect

Your first request

This walkthrough uses a team token: an API key that accesses one JukeHouse workspace. Run these commands from your terminal or server.

1. Create your key

Sign in, select the workspace you want to connect, and open API Keys. You need permission to manage API keys, and API access must be enabled for that workspace. If access is disabled, contact support. Copy the key when you create it; the full value is only shown once.

Open API Keys →

Store the key as an environment variable named JUKEHOUSE_API_KEY. Keep it on your server, out of browser code and source control.

This guide uses a team API key

Send a team key as Authorization: Token YOUR_API_KEY. It authenticates as that workspace, not as an individual person. Keep it on your server.

For requests on behalf of a signed-in JukeHouse user, the API also accepts JWT access tokens as Authorization: Bearer ACCESS_TOKEN. Actions that require a user identity, such as first-workspace onboarding, cannot use a team key.

Read the authentication guide →

2. Fetch your songs

Send your key in the Authorization header. This request reads up to 20 songs in the key’s workspace; it does not change your catalog.

The API base URL for this deployment is https://jukehouse.fm/api/v1/.

Request · terminal

curl --fail-with-body \
  -H "Authorization: Token $JUKEHOUSE_API_KEY" \
  -H "Accept: application/json" \
  "https://jukehouse.fm/api/v1/songs/?limit=20"

3. Read the response

A successful request returns HTTP 200. Songs are in results; count is the total for this query. Follow next until it is null to read the remaining pages.

An empty workspace returns count: 0 and results: []. That is a successful connection, not an error.

Save both identifiers: id is used for ordinary song reads and edits; uuid is used for registration actions. initial is the API value for a new draft.

Illustrative response · selected song fields

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [{
    "id": 123,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "title": "After the Rain",
    "artist": "Alex Morgan",
    "status": "initial",
    "status_display": "Draft"
  }]
}

02 / Build

Choose your next task

Read and sync your catalog

  1. Fetch your songs and follow each next URL until there are no more pages.
  2. Match records in your system using the JukeHouse song ID. Store date_modified to detect changes when you fetch them again.
  3. Read an individual song when you need its latest details. Search by title, artist, or ISWC using search.
Song fields and responses →

Example · find a song

curl --get \
  -H "Authorization: Token $JUKEHOUSE_API_KEY" \
  --data-urlencode "search=After the Rain" \
  --data-urlencode "ordering=-date_modified" \
  "https://jukehouse.fm/api/v1/songs/"

Use status=draft to filter new drafts. Responses retain the stored status value initial.

Create a song and submit its registration

  1. Create a draft and save its returned id and uuid.
  2. Add titles, songwriter/publisher shares, and the rights you want administered. Shares must total 100%; use the field definitions linked below.
  3. Read the registration summary and check the information before confirming.
  4. Submit through the confirmation action. Check its returned status; submission is not proof of society registration or royalty collection.

API reference for this workflow

Example · creates a draft in your workspace

curl -X POST \
  -H "Authorization: Token $JUKEHOUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"After the Rain","artist":"Alex Morgan"}' \
  "https://jukehouse.fm/api/v1/songs/"

After completing the song information, replace SONG_UUID below with the returned uuid.

GET  /api/v1/songs/SONG_UUID/registration/summary/
POST /api/v1/songs/SONG_UUID/registration/confirm/

Do not PATCH status to submit a song. Status changes through registration actions, not ordinary field edits.

Track registration progress

  1. Read the song’s registration summary using its uuid.
  2. Use song.status for application logic and song.status_display for the readable label. The summary also contains titles, shares, recordings, and rights.
  3. Refresh periodically at a rate that fits your workflow. Keep registration status separate from royalty income in your interface.
Registration summary fields →

Example · read the latest summary

curl \
  -H "Authorization: Token $JUKEHOUSE_API_KEY" \
  "https://jukehouse.fm/api/v1/songs/SONG_UUID/registration/summary/"

Keep the states distinct

For a first song, confirmation can return pending_activation; later songs can return validated. Neither means royalties have been collected.

03 / Go live

Make your integration dependable

Protect and rotate keys

Team tokens expire after 90 days and may be archived earlier. Plan to replace them before expiry. Never put a team key in a public app, repository, or log.

Handle errors explicitly

Check the HTTP status and error.code. Fix invalid data on 400, check the key on 401, and check access on 403. Save error.request_id when asking us to investigate.

Error response format →

Page through results and respect limits

Follow next links rather than guessing page URLs. Watch the X-RateLimit headers; if you receive 429, wait before retrying and honor Retry-After when supplied.

Rate limits →

Retry without duplicating work

Retry temporary read failures with increasing delays. If a create request times out, check whether it succeeded before sending it again. A repeated successful registration confirmation is safe and returns idempotent: true.

Keep building. We’re here to help.

Use the reference for exact fields and response shapes. If you’re unsure how your workflow fits, talk to us.

Open API reference Download OpenAPI Get integration help →