Workflows

Use this page as the sequence map for common integrations. Each workflow lists the calls in the order an integration should usually make them, the reference fields to keep, and the state checks that prevent failed submissions.

Integration posture

• Authenticate first with POST /api/v1/token, then send Authorization: Bearer ... on every request.
• Store only public references such as user_id, role_id, artist_id, release_id, track_id, checkout_id, smartlink_id, and review_id.
• Treat embedded_checkout_token as short-lived payment data. Do not log it or store it as a durable checkout reference.
• Use X-User-Id only for supported catalog workflows when an integration needs to act for a user in the same organization.
• For list endpoints, read meta.current_page, meta.per_page, meta.total, and meta.last_page before scheduling the next page.

Copy-ready snippets

Use these short recipes as starting points for each major endpoint group. Replace only the public references with values returned by earlier API calls.

Authentication and profile

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/token' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000' \
  --header 'X-Api-Secret: 0000000000000000000000000000000000000000'

curl 'https://enterprise.spacemedia.uk/api/v1/me' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e'

Users and members

curl 'https://enterprise.spacemedia.uk/api/v1/member-roles' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e'

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/users' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{"email":"eli.brooks@northstar-distribution.co.uk","role_ids":["c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e"]}'

Catalog delivery

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/artists' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'X-User-Id: 9d7046b2-3ab1-4c9d-9bd8-90bbd22b7df2' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Nova Vale","spotify_id":"3q7HBObVc0L8jNeTe5Gofh"}'

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/tracks' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'X-User-Id: 9d7046b2-3ab1-4c9d-9bd8-90bbd22b7df2' \
  --header 'Content-Type: application/json' \
  --data '{"title":"Midnight Atlas","release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","audio_file_id":"audio_1783157400_6f9c2b8e4d1a","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","type":"Primary Artist"},{"artist_id":"28636f32-61a4-41b8-8af4-70813049b9aa","type":"Composer"}],"language":"English","license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","links":["https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav"]}'

Billing and checkouts

curl 'https://enterprise.spacemedia.uk/api/v1/billing/overview' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e'

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/order/checkout/verify' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1"}'

Add-ons

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/addons/release-smartlinks/checkout' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{"version":"v1.0.0","cycle":"monthly","return_to":"/addons/smartlinks"}'

Copyright wallet

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/copyright/wallet/top-up' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{"currency":"EUR","package_code":"eur_100"}'

Smartlinks

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/smartlinks' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","slug":"nova-vale-midnight-atlas","title":"Midnight Atlas","links":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","is_visible":true,"sort_order":0}]}'

Branding and email theme

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/theme-editor/draft' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{"config":{"preset":"default","radius":"md","scale":"sm","contentLayout":"centered","font":"default","brand":"default","accent":"default"}}'

Feedback

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/platform-feedback' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{"category":"idea","message":"Release import is ready for a webhook callback option.","page_url":"https://enterprise.spacemedia.uk/releases"}'

User and member setup

Use the Users API when you need a full artist or catalog user account. Use the Team Members add-on when you need team access, role permissions, invitations, and admin workflows.

1. List role references with GET /api/v1/member-roles.
2. Create a user with POST /api/v1/users.
3. Store the returned user_id and role role_id values.
4. For team access, invite members with POST /api/v1/members/invite.
5. Confirm invitation state with GET /api/v1/member-invitations.
6. Update role permissions only through POST /api/v1/member-roles/{role_id}/permissions.

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/users' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "eli.brooks@northstar-distribution.co.uk",
    "role_ids": ["c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e"]
  }'

The invited user sets their own name when they accept the invitation, so this endpoint takes only the email and the roles. role_ids is required whenever the Team Members add-on is active, and each value is a role_id from GET /api/v1/member-roles.

Do not pass organization references in public requests. The organization is resolved from the authenticated API context.

Release delivery

Release delivery is a multi-step workflow. Create stable artist and release records first, then upload audio, create tracks against the release, and submit only after metadata, rights, and destinations pass readiness checks.

1. Create or reuse artists with POST /api/v1/artists.
2. Create the release shell with POST /api/v1/releases.
3. Upload master audio with POST /api/v1/tracks/upload.
4. Create tracks with POST /api/v1/tracks, using the returned audio_file_id and the release release_id.
5. Reorder tracks with POST /api/v1/releases/{release_id}/tracks/reorder when the release has more than one track.
6. Save rights metadata with POST /api/v1/releases/{release_id}/license.
7. Save delivery channels with POST /api/v1/releases/{release_id}/distribution.
8. Run readiness checks with GET /api/v1/releases/{release_id}/pre-qc.
9. Submit with POST /api/v1/releases/{release_id}/submit.
10. Track review queues through GET /api/v1/qc/releases/submitted, GET /api/v1/qc/releases/sent, or GET /api/v1/qc/releases/all when the authenticated user has access.

Keep these references:

Billing and checkout

Billing flows return either a redirect URL, an embedded checkout token, or a saved payment method reference. Store the durable public checkout reference, then poll or verify status through the matching endpoint.

1. Read billing state with GET /api/v1/billing/overview.
2. Start a subscription checkout, add-on checkout, credit top-up, or payment method setup.
3. Store checkout_id with your local order or billing action.
4. If an embedded_checkout_token is returned, hand it directly to your payment UI.
5. Redirect users with redirect_url only when the response uses hosted checkout.
6. Verify status with the matching status or verify endpoint before unlocking paid features.

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/copyright/wallet/top-up' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{
    "currency": "EUR",
    "package_code": "eur_100"
  }'

Copyright wallet top-ups settle in EUR or USD only. Package codes follow the currency: eur_50, eur_100, eur_250, usd_50, usd_100, usd_250. Return URLs are not part of this request; use the returned checkout reference and verify status through the matching endpoint.

Smartlinks

Smartlinks are release landing pages with managed destination links, analytics, and preference controls.

1. Confirm the Smartlink add-on is active.
2. Create a smartlink with POST /api/v1/smartlinks.
3. Store smartlink_id and public_url.
4. Use PUT /api/v1/smartlinks/{smartlink_id} for metadata or destination updates.
5. Use POST /api/v1/smartlinks/{smartlink_id}/sync after release metadata changes.
6. Read analytics with GET /api/v1/smartlinks/{smartlink_id}/analytics.
7. Use preference endpoints to manage user-level and organization-level behavior.

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/smartlinks' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{
    "release_id": "b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8",
    "slug": "nova-vale-midnight-atlas",
    "title": "Midnight Atlas",
    "links": [
      {
        "platform": "spotify",
        "url": "https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z",
        "is_visible": true,
        "sort_order": 0
      },
      {
        "platform": "apple_music",
        "url": "https://music.apple.com/gb/album/midnight-atlas/1784529016",
        "is_visible": true,
        "sort_order": 1
      }
    ]
  }'

Destinations are sent as links. Each entry needs platform and url; title, source, sort_order, and is_visible are optional. release_id, slug, and title on the smartlink itself are all optional, so you can create a standalone landing page that is not tied to a release.

Copyright wallet and release checks

Copyright endpoints expose organization-visible wallet balances, transactions, release checks, and top-ups.

1. Read summary with GET /api/v1/copyright/summary.
2. Read wallet state with GET /api/v1/copyright/wallet.
3. Create a wallet top-up when more credits are required.
4. Poll GET /api/v1/copyright/wallet/top-up/{checkout_id}/status.
5. List release checks with GET /api/v1/copyright/releases.
6. Open a release check with GET /api/v1/copyright/releases/{release_id}.

Top-ups and checks are scoped to the authenticated organization. Public responses use wallet_id, top_up_id, wallet_transaction_id, release_id, track_id, and copyright_check_id.

Branding and communication

Use these APIs when an organization admin needs automation around branding, email appearance, support details, legal pages, and public customer-facing settings.

1. Read current branding or theme profile.
2. Save drafts through the draft endpoint.
3. Preview before publishing.
4. Publish only after the admin has reviewed the rendered result.
5. Use support, terms, privacy, domain, and SSO guides for admin-facing setup rules that are not purely API driven.

Branding calls should use semantic colors, published profile references, and organization-visible settings only. Never infer internal organization references from a dashboard URL.

Failure handling

• 401 means the token is missing, expired, or invalid.
• 403 means the authenticated user or integration lacks access to that action.
• 404 means the public reference is unknown in the organization context, or the workflow is intentionally hidden from this role.
• 409 means a state transition is blocked by the current workflow state.
• 422 means validation failed. Read errors and retry only after correcting the request payload.