SDK Generation
The Enterprise API is documented with an OpenAPI contract that can be used to generate internal or customer-specific clients. Official SDK packages should follow the same public contract and naming rules as the API documentation.
SDK authors should also read Rate Limits and Retries, Delivery Statuses, and LLM Context. Generated clients should protect customers from duplicate writes and unsafe assumptions.
Contract rules
- Use the published OpenAPI file as the source of truth.
- Keep operation names stable and descriptive.
- Preserve public reference fields such as
user_id,role_id,artist_id,release_id,track_id,checkout_id,smartlink_id, andreview_id. - Do not expose numeric record references, organization references, provider payment references, or duplicate
idanduuidfields. - Treat
embedded_checkout_tokenas short-lived payment data and never as a durable checkout reference. - Treat
audio_file_idas a temporary upload reference. Use the returnedtrack_idafter creating a track.
Client behavior
- Send
Authorization: Bearer ...on every protected request. - Retry only idempotent reads automatically. For create, checkout, submit, publish, install, and top-up actions, retry only after checking the returned state.
- Parse
errorson422responses and return field-level validation feedback to operators. - Read
meta.current_page,meta.last_page,meta.per_page, andmeta.totalon paginated responses. - Keep
X-User-Idsupport explicit and limited to supported same-organization catalog workflows.
Customer generation
Customers can generate their own client from the published OpenAPI file. Pin the downloaded spec in your build so SDK behavior changes only when your team intentionally updates it.
curl --output spacemedia-enterprise-openapi.json \
'https://docs.spacemedia.uk/delivery-api/openapi.json'Recommended generator settings:
| Area | Recommendation |
|---|---|
| Operation names | Preserve operationId values from the spec. |
| Unknown fields | Keep unknown response fields accessible so new non-breaking fields do not break clients. |
| Errors | Map API error envelopes to typed exceptions or result objects. |
| Pagination | Expose data and meta together. |
| Uploads | Support multipart requests for audio, chunked audio, cover art, and document uploads. |
| Retries | Disable automatic retries for writes unless the SDK first reads current state. |
| Tokens | Store bearer tokens securely and refresh before expiry. |
SDK readiness checklist
| Area | Expectation |
|---|---|
| Authentication | Token exchange, token expiry, and bearer header handling are implemented. |
| Errors | 401, 403, 404, 409, and 422 are mapped to useful client exceptions or result objects. |
| Pagination | Collection helpers expose pagination metadata and stop conditions. |
| Uploads | Audio upload helpers return audio_file_id; track creation helpers return track_id. |
| Checkouts | Hosted and embedded checkout helpers store checkout_id and protect embedded_checkout_token. |
| Release workflow | Artist, release, track, license, distribution, readiness, and submit helpers preserve workflow order. |
| Naming | Public field names match the examples in this documentation. |
Common questions
Which contract should I generate from? The published OpenAPI specification only. Do not hand-edit a generated client to work around a contract you disagree with; report the mismatch instead.
Should the SDK rename fields to match my language conventions?
Keep the public reference names intact in the wire model. Renaming release_id to something generic is how integrations lose the ability to reconcile with support.
How should a generated client handle unknown enum values? Pass them through. Strict enums break on the next compatible addition.
Should the SDK retry automatically? Reads yes, writes no. See Rate Limits and Retries for retry safety by operation type.
Was this page helpful?