How the API Works

Four ideas explain almost everything about how this API behaves. Understanding them up front saves a lot of debugging later.

1. Scope comes from the credential

There is no organization parameter anywhere in the API. The credential you authenticate with determines which organization you operate in, and nothing you send can change that.

A 404 therefore means "not found in your organization", which is often the real answer when an identifier looks valid but belongs to someone else.

2. Authorization is capability-based

Each API client carries an explicit list of capabilities such as catalog:read or billing:write. New credentials start with catalog:read and nothing else.

Capabilities belong to the client, not to a person. They do not inherit from a staff member's dashboard role. When an integration acts for one of your users, that supplies catalog ownership context, not extra authority. See Authentication and Acting for Users.

A 403 means the endpoint exists and you are authenticated, but a capability, permission, or add-on check failed. It is never a signal to retry.

3. Some endpoint groups need an add-on as well

Buying API access does not expose product areas you have not bought.

Endpoint group	Also requires
Members and member roles	Team Members add-on active
Smartlinks create, update, sync, preferences, analytics	Smartlink add-on active
Theme editor draft and publish	Theme Editor active
Add-on checkout and install actions	The authenticated admin can manage add-ons
DDEX and enterprise webhooks	Explicit DDEX or webhook capabilities plus current staging onboarding. Production use starts only after SpaceMedia confirms route and connection activation

4. Every response uses the same envelope

Responses carry success, an optional message, data, an optional meta for pagination, and an optional errors map. Objects identify themselves with one stable public reference such as user_id, release_id, track_id, or checkout_id.

Internal numeric identifiers are never part of the public API. See Response Conventions.

Endpoint families

Family	Scope
Auth	Exchange organization API key and secret for a bearer token, then validate token expiry.
Account	Current profile, sessions, personal information, notification preferences, and custom labels.
Artists, releases, tracks	Catalog workflows available to permitted organization users.
Splits	Revenue split listing, creation, updates, and confirmations.
Users and members	Organization users, team members, invitations, roles, permissions, suspension, and related records where allowed.
Packages and payments	Membership packages, pay-per-release plans, upgrade options, subscriptions, checkouts, credit purchases, payment methods, and checkout verification.
Add-ons	Organization add-on checkout, install, activation, deactivation, uninstall, and status actions.
Copyright	Organization copyright summary, statistics, wallet reads, wallet top-ups, release reads, and top-up status.
Release review	Release review queues where the organization has dashboard access.
Smartlinks	Branded release landing pages, DSP destinations, analytics, and preferences.
Theme and email theme	Organization branding drafts, preview, and publish actions.
Feedback	Organization-visible feedback submission for product, catalog, billing, and API workflows.
Reference	Countries and release territories.
DDEX	Versioned partner connections, validations, exports, deliveries, imports, acknowledgements, and conformance workflows for approved Enterprise Delivery API customers.
Enterprise webhooks	Signed DDEX lifecycle events, delivery attempts, testing, replay, pause, and secret rotation.
WordPress OAuth	Registration, PKCE consent, and read-only catalog access for a WordPress plugin. Uses its own short-lived token, not an organization bearer token. See Authentication.

Base URLs

Environment	Base URL
Production	`https://enterprise.spacemedia.uk`
Staging	`https://staging.spacemedia.uk`

Use separate credentials per environment.

Common questions

Is the API public in the sense of unauthenticated? No. Public means an external organization can call it after credential, capability, and permission checks pass.

Can one credential reach two organizations? No. If you operate several organizations, you need separate credentials for each.

Does the playground send real requests? Yes, to whichever base URL is selected. Use sample values until you are deliberately testing with your own credentials, and never paste production secrets into a shared session.

Where do I find the exact request and response shape? On the endpoint page for that operation. Those pages are generated from the OpenAPI contract, which is authoritative.

Work through the Quickstart, then follow the recipe that matches your integration in Workflows.