{"openapi":"3.1.0","info":{"title":"SpaceMedia Delivery API","version":"2026-07","description":"Build organization-scoped music distribution integrations with the SpaceMedia Delivery API. Exchange an organization API key and secret at POST /api/v1/token, reuse the returned bearer token until shortly before expires_at, and send only stable public references such as user_id, artist_id, release_id, track_id, role_id, and checkout_id. Production and staging use separate credentials and data. Catalog ownership operations require a same-organization X-User-Id when stated by the operation. The contract covers catalog creation, audio and artwork upload, release readiness and review, delivery configuration, billing, add-ons, members, branding, smartlinks, copyright workflows, DDEX, and signed enterprise webhooks. DDEX and enterprise webhook routes are currently available in staging for onboarding and conformance; do not use them in production until SpaceMedia confirms production route and connection activation. Follow Retry-After on 429 responses, do not automatically retry high-impact mutations unless the operation supports Idempotency-Key, and verify resource state after an uncertain outcome. Numeric record references, system-only operations, dashboard routes, payment-provider secrets, and backend implementation details are not part of this public contract. Start with https://docs.spacemedia.uk/delivery-api/api-quickstart and use https://docs.spacemedia.uk/delivery-api/go-live-checklist before production cutover."},"servers":[{"url":"https://enterprise.spacemedia.uk","description":"Production"},{"url":"https://staging.spacemedia.uk","description":"Staging"}],"x-spacemedia-capability-policy":{"description":"GET, HEAD, and OPTIONS use the read capability. Other methods use the write capability. A path not covered by this allowlist is not part of the organization integration API.","default_new_client_capabilities":["catalog:read"],"rules":[{"path_prefix":"/api/v1/account-settings","read":"account:read","write":"account:write"},{"path_prefix":"/api/v1/labels","read":"account:read","write":"account:write"},{"path_prefix":"/api/v1/addons","read":"addons:read","write":"addons:manage"},{"path_prefix":"/api/v1/billing","read":"billing:read","write":"billing:write"},{"path_prefix":"/api/v1/subscriptions","read":"billing:read","write":"billing:write"},{"path_prefix":"/api/v1/order","read":"billing:read","write":"billing:write"},{"path_prefix":"/api/v1/packages","read":"billing:read","write":"billing:write"},{"path_prefix":"/api/v1/upgrade","read":"billing:read","write":"billing:write"},{"path_prefix":"/api/v1/theme-editor","read":"branding:read","write":"branding:manage"},{"path_prefix":"/api/v1/email-theme","read":"branding:read","write":"branding:manage"},{"path_prefix":"/api/v1/artists","read":"catalog:read","write":"catalog:write"},{"path_prefix":"/api/v1/releases","read":"catalog:read","write":"catalog:write"},{"path_prefix":"/api/v1/tracks","read":"catalog:read","write":"catalog:write"},{"path_prefix":"/api/v1/splits","read":"catalog:read","write":"catalog:write"},{"path_prefix":"/api/v1/smartlinks","read":"catalog:read","write":"catalog:write"},{"path_prefix":"/api/v1/countries","read":"catalog:read","write":"catalog:write"},{"path_prefix":"/api/v1/pre-qc","read":"catalog:read","write":"catalog:write"},{"path_prefix":"/api/v1/copyright","read":"copyright:read","write":"copyright:write"},{"path_prefix":"/api/v1/ddex","read":"ddex:read","write":"ddex:write"},{"path_prefix":"/api/v1/members","read":"members:read","write":"members:manage"},{"path_prefix":"/api/v1/member-invitations","read":"members:read","write":"members:manage"},{"path_prefix":"/api/v1/member-roles","read":"members:read","write":"members:manage"},{"path_prefix":"/api/v1/member-permissions","read":"members:read","write":"members:manage"},{"path_prefix":"/api/v1/qc","read":"review:read","write":"review:process"},{"path_prefix":"/api/v1/users","read":"users:read","write":"users:manage"},{"path_prefix":"/api/v1/webhooks","read":"webhooks:read","write":"webhooks:manage"},{"path_prefix":"/api/v1/platform-feedback","read":"feedback:write","write":"feedback:write"}],"operation_overrides":{"createDdexSenderIdentity":"ddex:manage","createDdexConnection":"ddex:manage","requestDdexConnectionActivation":"ddex:manage","updateDdexConnectionSecret":"ddex:manage","startDdexConnectionHealthCheck":"ddex:manage","createDdexDealProfile":"ddex:manage"},"acting_user":{"capability":"users:act-as","header":"X-User-Id","description":"Required only on documented catalog ownership and upload operations."}},"tags":[{"name":"Authentication","description":"Exchange organization credentials for an opaque bearer token and inspect the authenticated API client context."},{"name":"WordPress OAuth","description":"Register a verified WordPress installation, authorize read-only catalog access with PKCE, rotate short-lived tokens, synchronize releases, and revoke the connection."},{"name":"Account Settings","description":"Read and update organization-visible account settings, sessions, notification preferences, personal information, and labels."},{"name":"Reference Data","description":"Discover public country, territory, and distribution-channel values instead of hardcoding dashboard labels."},{"name":"Artists","description":"Create and maintain artist profiles used by releases, tracks, credits, and catalog search."},{"name":"Releases","description":"Create releases, upload artwork, configure rights and destinations, check readiness, manage track order, and submit for review."},{"name":"Tracks","description":"Upload audio, create and update track metadata, attach tracks to releases, inspect upload progress, and manage supporting documents."},{"name":"Revenue Splits","description":"Create, update, list, and confirm revenue splits using public user and catalog references."},{"name":"Users","description":"Manage organization users and read their scoped artists, releases, tracks, revenue, and split records."},{"name":"Plans and Upgrades","description":"Discover membership plans, pay-per-release options, and organization upgrade choices before checkout."},{"name":"Billing and Checkouts","description":"Create and verify release, subscription, credit, and payment-method workflows without exposing provider credentials."},{"name":"Add-Ons","description":"Purchase, install, activate, deactivate, and uninstall organization add-ons with explicit status verification."},{"name":"Copyright","description":"Read copyright summaries and release results, inspect wallet activity, and create or verify wallet top-ups."},{"name":"Release Review","description":"Read organization-visible submitted, sent, and combined release review queues for operational monitoring."},{"name":"Members","description":"Manage team members, invitations, roles, permissions, suspension, and access lifecycle within the organization."},{"name":"Smartlinks","description":"Create and manage release smartlinks, destination links, preferences, synchronization, publication status, and analytics."},{"name":"Theme Editor","description":"Read, save, and publish organization theme profiles for supported whitelabel surfaces."},{"name":"Email Theme","description":"Preview, save, read, and publish branded transactional-email theme settings."},{"name":"Feedback","description":"Submit organization-visible product and integration feedback with safe diagnostic context."},{"name":"DDEX","description":"Configure approved partner connections and manage ERN validation, export, delivery, import, claim, acknowledgement, retry, and conformance workflows."},{"name":"Enterprise Webhooks","description":"Subscribe to signed DDEX lifecycle events, inspect delivery attempts, test receivers, replay events, and rotate reveal-once secrets."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Bearer token"},"WordPressOAuthBearer":{"type":"http","scheme":"bearer","bearerFormat":"Short-lived WordPress OAuth access token","description":"Access token issued by the WordPress OAuth token endpoint. It is separate from organization Delivery API bearer tokens."}},"parameters":{"DdexReference":{"name":"reference","in":"path","required":true,"description":"Stable public reference returned by the DDEX gateway.","schema":{"type":"string","format":"uuid"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique request key. Reuse with the same body replays the result; reuse with a different body returns a conflict.","schema":{"type":"string","minLength":8,"maxLength":255}},"Page":{"name":"page","in":"query","required":false,"description":"One-based result page. Defaults to 1.","schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"size","in":"query","required":false,"description":"Results per page. Values are clamped to the range 1 through 100. The legacy per_page alias is also accepted.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"ActingUser":{"name":"X-User-Id","in":"header","required":true,"description":"Public user_id in the API client organization. Requires users:act-as and supplies catalog ownership and quota context.","schema":{"type":"string","format":"uuid"}}},"responses":{"DdexAccepted":{"description":"The gateway accepted the asynchronous operation and returned its canonical status URL and correlation key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdexOperation"},"example":{"data":{"reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","status":"ready","review_status":"not_required","transport_status":"not_started","partner_status":"not_started","findings":[]},"status_url":"/api/v1/ddex/messages/45be9e79-f39e-4cf9-bfc8-bf9f10481da6","correlation_key":"ddex_01J2M4Y8Q7K3"}}}},"DdexConnectionHealthAccepted":{"description":"Connection health and readiness were evaluated without returning credentials. Staging sandbox checks may be simulated without an external probe.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"required":["reference","issues","simulated","external_probe_performed"],"properties":{"reference":{"type":"string","format":"uuid"},"issues":{"type":"array","items":{"type":"string"}},"simulated":{"type":"boolean","description":"True when the isolated staging simulator evaluated the check."},"external_probe_performed":{"type":"boolean","description":"True only when this request actually contacted the configured partner endpoint."}}}}},"example":{"data":{"reference":"3bc1f628-60af-4db2-b984-321c1525df20","name":"Partner sandbox","partner_name":"Partner DSP","commercial_route":"direct_partner","direction":"outbound","environment":"sandbox","status":"testing","review_status":"approved","conformance_status":"testing","transport_enabled":false,"local_dpid":"PA-DPIDA-2026072901-N","remote_dpid":"PA-DPIDA-2026072902-N","ern_version":"4.3.2","release_profile":"Audio","avs_version":"011","choreography":"web_service_1_8","hosting_mode":"spacemedia_managed","auth_type":"bearer","capabilities":["insert","update","global_takedown"],"health":{"status":"healthy","checked_at":"2026-07-30T15:20:00Z"},"version":1,"credentials_configured":true,"credentials_rotated_at":"2026-07-30T15:10:00Z","issues":[],"simulated":true,"external_probe_performed":false}}}}},"DdexBatchAccepted":{"description":"The eligible messages were placed in one completed immutable batch manifest.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["reference","status","message_count","manifest_sha256","completed_at"],"properties":{"reference":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["complete"]},"message_count":{"type":"integer","minimum":1},"manifest_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"completed_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"reference":"f71953fb-8bc7-4936-8752-ddd5ce6a9c14","status":"complete","message_count":2,"manifest_sha256":"8f92c85b22e8a04a05ba20b1bdcb85f83ba98f5c8cb27d244bcb0d6d7f8f4312","completed_at":"2026-07-30T15:25:00Z"}}}}},"DdexImportAccepted":{"description":"The inbound message was validated and an atomic create-only import result was returned.","content":{"application/json":{"schema":{"type":"object","required":["data","status_url","correlation_key"],"properties":{"data":{"type":"object","required":["reference","message_reference","status","creates_drafts_only"],"properties":{"reference":{"type":"string","format":"uuid"},"message_reference":{"type":"string","format":"uuid"},"status":{"type":"string"},"creates_drafts_only":{"type":"boolean","const":true}}},"status_url":{"type":"string"},"correlation_key":{"type":"string"}}},"example":{"data":{"reference":"9c45570e-98f3-4f8b-9811-6f16604b2d8d","message_reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","status":"completed","creates_drafts_only":true},"status_url":"/api/v1/ddex/imports/9c45570e-98f3-4f8b-9811-6f16604b2d8d","correlation_key":"ddex_01J2M4Y8Q7K3"}}}},"DdexAcknowledgementAccepted":{"description":"The acknowledgement or processing-status message was stored separately from claim state.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["reference","message_reference","type","status","received_at"],"properties":{"reference":{"type":"string","format":"uuid"},"message_reference":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["acknowledgement","processing_status"]},"status":{"type":"string"},"received_at":{"type":"string","format":"date-time"}}}}},"example":{"data":{"reference":"8c19c836-b795-4cc5-abf9-295a8767cfef","message_reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","type":"acknowledgement","status":"accepted","received_at":"2026-07-30T15:30:00Z"}}}}},"DdexValidationReport":{"description":"A downloadable, support-safe validation report for one DDEX message.","content":{"application/json":{"schema":{"type":"object","required":["message_reference","correlation_key","status","generated_at","findings"],"properties":{"message_reference":{"type":"string","format":"uuid"},"correlation_key":{"type":"string"},"status":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/DdexFinding"}}}},"example":{"message_reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","correlation_key":"ddex_01J2M4Y8Q7K3","status":"ready","generated_at":"2026-07-30T15:32:00Z","findings":[]}}}},"WebhookDeliveryAccepted":{"description":"A signed webhook delivery was queued and can be inspected through the delivery log.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["delivery_reference","status"],"properties":{"delivery_reference":{"type":"string","format":"uuid"},"replay_of":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}},"example":{"data":{"delivery_reference":"e2ae09fd-c3bc-446f-94fb-21a776fae9fb","status":"pending"}}}}},"DdexStandardsResponse":{"description":"Supported DDEX standards, profiles, choreography options, actions, and feature flags.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDataEnvelope"},"example":{"data":{"recommended":{"ern":"4.3.2","avs":"011","release_profile":"Audio","release_profile_standard":"2.3.1"},"generated_ern_versions":["4.3.2"],"inbound_ern_versions":["4.3.0","4.3.1","4.3.2"],"migration_only_ern_versions":["3.8.2"],"avs_versions":["011"],"profiles":["Audio","SimpleAudioSingle"],"choreographies":["web_service_1_8","cloud_storage_1_8_1"],"actions":["insert","update","territorial_takedown","global_takedown","purge"],"features":{"rest_first":true,"native_relay":true,"release_by_release":true,"batch":true,"imports_create_drafts_only":true,"automatic_downgrade":false},"schema_assets":{"installed":false,"required_for_validation":true,"required_for_live":true,"mutable_remote_schemas":false},"simulation":{"enabled":true,"licensed_schema_validation":false,"structural_semantic_validation":true,"external_delivery":false,"live_approval":false}}}}}},"DdexSenderIdentityResponse":{"description":"DDEX sender identity returned with its public reference and attestation state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDataEnvelope"},"example":{"data":{"reference":"4a077d69-e377-43cd-9abb-43f68cd73da1","name":"Example Records","dpid":"PA-DPIDA-2026073001-N","status":"attested"}}}}},"DdexSenderIdentityCollection":{"description":"Paginated DDEX sender identities. Records are nested at data.data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NestedPaginatorEnvelope"},"example":{"data":{"current_page":1,"data":[{"reference":"4a077d69-e377-43cd-9abb-43f68cd73da1","name":"Example Records","dpid":"PA-DPIDA-2026073001-N","status":"attested","attested_at":"2026-07-30T15:00:00Z"}],"last_page":1,"per_page":10,"total":1}}}}},"DdexConnectionResponse":{"description":"DDEX partner connection state returned without credential values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDataEnvelope"},"example":{"data":{"reference":"3bc1f628-60af-4db2-b984-321c1525df20","name":"Partner sandbox","partner_name":"Example DSP","commercial_route":"direct_partner","direction":"outbound","environment":"sandbox","status":"pending_review","review_status":"pending","conformance_status":"not_started","transport_enabled":false,"ern_version":"4.3.2","release_profile":"Audio","avs_version":"011","choreography":"web_service_1_8","health":{"status":"unknown","checked_at":null},"credentials_configured":true}}}}},"DdexConnectionCollection":{"description":"Paginated DDEX partner connections. Records are nested at data.data and never include credential values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NestedPaginatorEnvelope"},"example":{"data":{"current_page":1,"data":[{"reference":"3bc1f628-60af-4db2-b984-321c1525df20","name":"Partner sandbox","partner_name":"Example DSP","status":"testing","review_status":"approved","conformance_status":"testing","transport_enabled":false,"environment":"sandbox","health":{"status":"healthy","checked_at":"2026-07-30T15:20:00Z"},"credentials_configured":true}],"last_page":1,"per_page":10,"total":1}}}}},"DdexDealProfileResponse":{"description":"DDEX deal profile returned with its public reference and commercial terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDataEnvelope"},"example":{"data":{"reference":"91150ca4-aad3-4b5a-b041-d1cbd76d1421","name":"Premium subscription","commercial_model":"SubscriptionModel","use_types":["OnDemandStream"],"territories":["GB","US","DE"],"valid_from":"2026-08-01","valid_until":null,"terms":{"usage":"commercial"}}}}}},"DdexDealProfileCollection":{"description":"Paginated DDEX deal profiles. Records are nested at data.data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NestedPaginatorEnvelope"},"example":{"data":{"current_page":1,"data":[{"reference":"91150ca4-aad3-4b5a-b041-d1cbd76d1421","name":"Premium subscription","commercial_model":"SubscriptionModel","use_types":["OnDemandStream"],"territories":["GB","US","DE"]}],"last_page":1,"per_page":10,"total":1}}}}},"DdexBatchCollection":{"description":"Paginated DDEX delivery batches. Records are nested at data.data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NestedPaginatorEnvelope"},"example":{"data":{"current_page":1,"data":[{"reference":"f71953fb-8bc7-4936-8752-ddd5ce6a9c14","status":"complete","message_count":2,"manifest_sha256":"8f92c85b22e8a04a05ba20b1bdcb85f83ba98f5c8cb27d244bcb0d6d7f8f4312","completed_at":"2026-07-30T15:25:00Z"}],"last_page":1,"per_page":10,"total":1}}}}},"DdexImportResponse":{"description":"Canonical native import state and any draft releases created by the atomic import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDataEnvelope"},"example":{"data":{"reference":"9c45570e-98f3-4f8b-9811-6f16604b2d8d","message_reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","status":"completed","unmapped_fields":[],"created_release_references":["e781f408-69ed-469f-bfd5-082553048498"],"creates_drafts_only":true,"created_at":"2026-07-30T15:30:00Z"}}}}},"DdexImportCollection":{"description":"Paginated native DDEX imports. Records are nested at data.data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NestedPaginatorEnvelope"},"example":{"data":{"current_page":1,"data":[{"reference":"9c45570e-98f3-4f8b-9811-6f16604b2d8d","message_reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","status":"completed","unmapped_fields":[],"created_release_references":["e781f408-69ed-469f-bfd5-082553048498"],"creates_drafts_only":true,"created_at":"2026-07-30T15:30:00Z"}],"last_page":1,"per_page":10,"total":1}}}}},"DdexMessageResponse":{"description":"Canonical DDEX message state with public references and support-safe findings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDataEnvelope"},"example":{"data":{"reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","kind":"delivery","source":"release","action":"insert","status":"acknowledged","review_status":"not_required","transport_status":"transferred","partner_status":"accepted","webhook_status":"delivered","ern_version":"4.3.2","release_profile":"Audio","avs_version":"011","delivery_simulated":true,"findings":[]}}}}},"DdexMessageCollection":{"description":"Paginated DDEX messages. Records are nested at data.data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NestedPaginatorEnvelope"},"example":{"data":{"current_page":1,"data":[{"reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","kind":"delivery","source":"release","action":"insert","status":"ready","review_status":"not_required","transport_status":"not_started","partner_status":"not_started","webhook_status":"not_started","ern_version":"4.3.2","release_profile":"Audio","avs_version":"011"}],"last_page":1,"per_page":10,"total":1}}}}},"EnterpriseWebhookCollection":{"description":"Paginated enterprise webhook subscriptions. Records are nested at data.data and never include signing secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NestedPaginatorEnvelope"},"example":{"data":{"current_page":1,"data":[{"reference":"9f6529b3-218a-478f-a074-0830165889c5","name":"DDEX operations","endpoint_url":"https://integrator.example/webhooks/spacemedia","events":["ddex.delivery.status_changed","ddex.delivery.failed"],"active":true,"secret_configured":true,"secret_rotated_at":"2026-07-30T15:40:00Z","previous_secret_valid_until":null,"created_at":"2026-07-30T15:40:00Z"}],"last_page":1,"per_page":10,"total":1}}}}},"EnterpriseWebhookDeliveryCollection":{"description":"Paginated webhook delivery attempts. Records are nested at data.data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NestedPaginatorEnvelope"},"example":{"data":{"current_page":1,"data":[{"reference":"e2ae09fd-c3bc-446f-94fb-21a776fae9fb","event":"ddex.delivery.status_changed","resource_reference":"45be9e79-f39e-4cf9-bfc8-bf9f10481da6","status":"delivered","attempt_count":1,"last_http_status":204,"next_attempt_at":null,"delivered_at":"2026-07-30T15:45:00Z"}],"last_page":1,"per_page":10,"total":1}}}}},"Unauthorized":{"description":"Authentication failed because the bearer token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Forbidden":{"description":"The API client lacks the required DDEX capability or Enterprise Delivery API access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"NotFound":{"description":"The public resource reference was not found in the authenticated organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Conflict":{"description":"The operation conflicts with the current message, batch, review, or idempotency state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"ValidationFailed":{"description":"Input, DDEX, catalog, contract, transport, or state validation found blocking errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"The API client or partner connection exceeded its current request or concurrency allowance.","headers":{"Retry-After":{"description":"Seconds to wait before retrying a retryable operation.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalServerError":{"description":"An unexpected server error prevented the request from completing. Provide error_reference to SpaceMedia support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The request could not be completed.","error_code":"public_api_request_failed","error_reference":"fa711c5c-0704-4c8f-86dc-76719fbdbb02"}}}}},"schemas":{"PublicDataEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"description":"The public resource represented by this operation. See the response example for its fields."}}},"NestedPaginatorEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"required":["current_page","data","last_page","per_page","total"],"properties":{"current_page":{"type":"integer","minimum":1},"data":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Records on the current page."},"last_page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0}}}}},"DdexFinding":{"type":"object","additionalProperties":false,"required":["reference","code","family","severity","stage","retryable","explanation","correlation_key"],"properties":{"reference":{"type":"string","format":"uuid","description":"Stable public finding reference."},"code":{"type":"string","example":"DDEX_DPID_MISMATCH","description":"Stable machine-readable validation code."},"family":{"type":"string","example":"identity","description":"Validation error family."},"severity":{"type":"string","enum":["error","warning","info"],"description":"Whether the finding blocks processing."},"stage":{"type":"string","description":"Processing stage that produced the finding."},"retryable":{"type":"boolean","description":"Whether retrying unchanged input can reasonably succeed."},"location":{"type":["string","null"],"description":"JSON Pointer for REST input or XPath for native XML."},"explanation":{"type":"string","description":"Human-readable reason for the finding."},"remediation":{"type":["string","null"],"description":"Recommended client action."},"correlation_key":{"type":"string","description":"Support-safe correlation key for this operation."}}},"DdexOperation":{"type":"object","additionalProperties":false,"required":["data","status_url","correlation_key"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["reference","status","review_status","transport_status","partner_status","findings"],"properties":{"reference":{"type":"string","format":"uuid","description":"Stable public DDEX operation reference."},"status":{"type":"string","description":"Current control-plane state."},"review_status":{"type":"string","description":"SpaceMedia review state. Direct partner routes return not_required."},"transport_status":{"type":"string","description":"Transport state kept separate from review and partner processing."},"partner_status":{"type":"string","description":"Latest explicit processing state reported by the partner."},"findings":{"type":"array","items":{"$ref":"#/components/schemas/DdexFinding"}}}},"status_url":{"type":"string","description":"Canonical API path for polling current state."},"correlation_key":{"type":"string","description":"Support-safe correlation key."}}},"DdexOperationInput":{"type":"object","additionalProperties":false,"properties":{"connection_reference":{"type":"string","format":"uuid","description":"Versioned partner connection to use."},"release_reference":{"type":"string","format":"uuid","description":"SpaceMedia release to snapshot and package."},"native_xml":{"type":"string","maxLength":26214400,"description":"Native ERN XML up to 25 MiB, preserved byte-for-byte by the gateway."},"deal_profile_reference":{"type":"string","format":"uuid","description":"Explicit commercial deal profile for this operation."},"action":{"type":"string","enum":["insert","update","territorial_takedown","global_takedown","purge"],"description":"Requested DDEX lifecycle action."},"metadata_overlay":{"type":"object","additionalProperties":true,"description":"Versioned DDEX-only metadata that is absent from the release model."}},"required":["connection_reference","action"],"oneOf":[{"required":["release_reference"]},{"required":["native_xml"]}],"example":{"connection_reference":"3bc1f628-60af-4db2-b984-321c1525df20","release_reference":"e781f408-69ed-469f-bfd5-082553048498","deal_profile_reference":"91150ca4-aad3-4b5a-b041-d1cbd76d1421","action":"insert"}},"DdexConnection":{"type":"object","additionalProperties":false,"required":["reference","name","partner_name","commercial_route","direction","environment","status","review_status","conformance_status","transport_enabled","local_dpid","remote_dpid","ern_version","release_profile","avs_version","choreography","hosting_mode","auth_type","capabilities","health","version","credentials_configured"],"properties":{"reference":{"type":"string","format":"uuid"},"name":{"type":"string"},"partner_name":{"type":"string"},"commercial_route":{"type":"string","enum":["spacemedia_delivery_deal","direct_partner"]},"direction":{"type":"string","enum":["outbound","inbound","bidirectional"]},"environment":{"type":"string","enum":["sandbox","live"]},"status":{"type":"string","enum":["draft","pending_review","testing","approved","active","rejected","suspended","superseded"]},"review_status":{"type":"string","enum":["not_submitted","pending","in_review","approved","rejected"]},"conformance_status":{"type":"string","enum":["not_started","testing","passed","failed"]},"conformance_evidence_reference":{"type":["string","null"]},"transport_enabled":{"type":"boolean"},"local_dpid":{"type":"string"},"remote_dpid":{"type":"string"},"ern_version":{"type":"string"},"release_profile":{"type":"string"},"avs_version":{"type":"string"},"choreography":{"type":"string","enum":["web_service_1_8","cloud_storage_1_8_1"]},"hosting_mode":{"type":"string","enum":["spacemedia_managed","partner_managed"]},"auth_type":{"type":"string","enum":["basic","bearer","sftp_password","sftp_key"]},"agreement_reference":{"type":["string","null"]},"capabilities":{"type":["array","null"],"items":{"type":"string"}},"health":{"type":"object","additionalProperties":false,"required":["status","checked_at"],"properties":{"status":{"type":"string","enum":["unknown","healthy","degraded"]},"checked_at":{"type":["string","null"],"format":"date-time"}}},"version":{"type":"integer","minimum":1},"credentials_configured":{"type":"boolean"},"credentials_rotated_at":{"type":["string","null"],"format":"date-time"},"activation_requested_at":{"type":["string","null"],"format":"date-time"},"conformance_checked_at":{"type":["string","null"],"format":"date-time"},"reviewed_at":{"type":["string","null"],"format":"date-time"},"activated_at":{"type":["string","null"],"format":"date-time"},"readiness":{"type":"object","additionalProperties":true,"description":"Applicable activation checks and remediation. Platform approval evidence is not exposed."}}},"DdexConnectionResult":{"type":"object","additionalProperties":false,"required":["data","secret_values_returned"],"properties":{"data":{"$ref":"#/components/schemas/DdexConnection"},"secret_values_returned":{"type":"boolean","const":false,"description":"DDEX partner credentials are accepted for storage but are never returned."}},"example":{"data":{"reference":"3bc1f628-60af-4db2-b984-321c1525df20","name":"Partner sandbox","partner_name":"Example DSP","commercial_route":"direct_partner","direction":"outbound","environment":"sandbox","status":"draft","review_status":"not_submitted","conformance_status":"not_started","transport_enabled":false,"local_dpid":"PA-DPIDA-2026073001-N","remote_dpid":"PA-DPIDA-2026073002-N","ern_version":"4.3.2","release_profile":"Audio","avs_version":"011","choreography":"web_service_1_8","hosting_mode":"partner_managed","auth_type":"bearer","capabilities":["insert","update","global_takedown"],"health":{"status":"unknown","checked_at":null},"version":1,"credentials_configured":true,"credentials_rotated_at":"2026-07-30T15:10:00Z"},"secret_values_returned":false}},"EnterpriseWebhookSubscription":{"type":"object","additionalProperties":true,"required":["reference","name","endpoint_url","events","active","secret_configured","secret_rotated_at","previous_secret_valid_until","created_at"],"properties":{"reference":{"type":"string","format":"uuid"},"name":{"type":"string"},"endpoint_url":{"type":"string","format":"uri","pattern":"^https://"},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["ddex.delivery.status_changed","ddex.delivery.blocked","ddex.delivery.acknowledged","ddex.delivery.rejected","ddex.delivery.failed","ddex.import.completed","ddex.import.failed","ddex.connection.degraded"]}},"active":{"type":"boolean"},"secret_configured":{"type":"boolean"},"secret_rotated_at":{"type":["string","null"],"format":"date-time"},"previous_secret_valid_until":{"type":["string","null"],"format":"date-time","description":"During rotation, outgoing signatures include both current and previous HMAC values until this time."},"created_at":{"type":["string","null"],"format":"date-time"}},"example":{"reference":"9f6529b3-218a-478f-a074-0830165889c5","name":"DDEX operations","endpoint_url":"https://integrator.example/webhooks/spacemedia","events":["ddex.delivery.status_changed","ddex.delivery.failed"],"active":true,"secret_configured":true,"secret_rotated_at":"2026-07-30T15:40:00Z","previous_secret_valid_until":null,"created_at":"2026-07-30T15:40:00Z"}},"EnterpriseWebhookSecretResult":{"type":"object","additionalProperties":false,"required":["data","secret_values_returned"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/EnterpriseWebhookSubscription"},{"type":"object","required":["signing_secret"],"properties":{"signing_secret":{"type":"string","format":"password","writeOnly":true,"x-sensitive":true,"description":"Reveal-once signing secret. Store it immediately and never log it."}}}]},"secret_values_returned":{"type":"boolean","const":true}},"example":{"data":{"reference":"9f6529b3-218a-478f-a074-0830165889c5","name":"DDEX operations","endpoint_url":"https://integrator.example/webhooks/spacemedia","events":["ddex.delivery.status_changed","ddex.delivery.failed"],"active":true,"secret_configured":true,"secret_rotated_at":"2026-07-30T15:40:00Z","previous_secret_valid_until":null,"created_at":"2026-07-30T15:40:00Z","signing_secret":"smwh_example_store_securely_and_never_log"},"secret_values_returned":true}},"ApiError":{"type":"object","additionalProperties":true,"required":["success","message"],"properties":{"success":{"type":"boolean","example":false,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Validation failed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"errors":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"array","items":{"type":"string","example":"The title field is required."},"description":"Catalog or content title shown in the dashboard and API responses."}},"description":"Validation errors keyed by request field. Each entry contains one or more human-readable messages."},"error_code":{"type":"string","description":"Stable machine-readable failure code when the error was reported by an application workflow."},"error_reference":{"type":"string","format":"uuid","description":"Support-safe reference for a reported server failure."}},"description":"ApiError object returned by the public organization API."},"User":{"type":"object","additionalProperties":false,"required":["user_id","name","email","verified","is_invited","is_suspended"],"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this user."},"full_name":{"type":"string","example":"Maya Chen","description":"Full display name assembled from the account profile fields."},"first_name":{"type":"string","example":"Maya","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Chen","description":"Family name for the user or member profile."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account or invitation."},"phone":{"type":"string","example":"+442071838750","description":"Phone number on the account profile when provided."},"language":{"type":"string","example":"en","description":"Primary language value used for profile, release, or track metadata."},"country":{"type":"string","example":"United Kingdom","description":"Country associated with the user, artist, or organization record."},"profile_photo":{"type":"string","example":"https://assets.spacemedia-docs.invalid/users/maya-chen/profile-photo.webp","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"verified":{"type":"boolean","example":true,"description":"Whether the account email or identity state is verified."},"email_verified_at":{"type":"string","example":"2026-06-25T08:15:00+00:00","format":"date-time","description":"Timestamp for when email verified occurred, formatted as ISO 8601 when available."},"last_login_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last login occurred, formatted as ISO 8601 when available."},"invitation_status":{"type":"string","example":"accepted","description":"Invitation lifecycle status, such as pending or accepted."},"is_invited":{"type":"boolean","example":false,"description":"Whether this user was created through an organization invitation."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this user."}}},"description":"Roles assigned to the user or member within the organization."},"organization_name":{"type":"string","example":"Northstar Distribution","description":"Organization display name shown for context. This is not an organization identifier and cannot be used to switch organization scope."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"User object returned by the public organization API."},"Artist":{"type":"object","additionalProperties":false,"required":["artist_id","name"],"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Stable public artist reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artist."},"artist_type":{"type":"string","example":"Primary Artist","description":"Artist classification used for DSP metadata and credit display."},"spotify_id":{"type":"string","example":"3mY7kJqR8B2nQvP6LxT4Za","description":"Optional external Spotify artist reference for matching catalog profiles. It is not a SpaceMedia API path reference; use artist_id for SpaceMedia API calls."},"bio":{"type":"string","example":"Electronic artist and producer from London.","description":"Artist biography or descriptive profile text."},"country":{"type":"string","example":"GB","description":"Country associated with the user, artist, or organization record."},"releases_count":{"type":"integer","example":2,"description":"Number of releases currently associated with the artist."},"tracks_count":{"type":"integer","example":7,"description":"Number of tracks currently associated with the artist."},"total_streams":{"type":"integer","example":125000,"description":"Total reported streams when reporting data is available."},"created_at":{"type":"string","example":"2026-06-01T11:00:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Artist object returned by the public organization API."},"Release":{"type":"object","additionalProperties":false,"required":["release_id","title","status","artists"],"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"Whether copyright checking is enabled for the organization or release workflow."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"release_review":{"type":["object","null"],"additionalProperties":false,"properties":{"review_id":{"type":"string","example":"f07b26d4-4ab6-4b46-8b4d-2d95c0a4f25d","format":"uuid","description":"Stable public review reference for the release review workflow."},"review_status":{"type":"string","example":"ready_for_review","description":"Organization-visible review status for the release."},"delivery_status":{"type":"string","example":"pending","description":"Organization-visible delivery status returned by the release review workflow."},"delivery_simulated":{"type":"boolean","example":false,"description":"True only when staging completed the delivery lifecycle locally without contacting a DSP or delivery partner."}},"description":"Current review and delivery state when a release has entered review."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this release."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this release."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account or invitation."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Release object returned by the public organization API."},"Track":{"type":"object","additionalProperties":false,"required":["track_id","title","artists","documents_requested"],"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this track."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"track_version":{"type":"string","example":"Original Mix","description":"Version label for the track, such as remix, radio edit, instrumental, or acoustic version."},"isrc_code":{"type":"string","example":"GBSMU2600001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"iswc_code":{"type":"string","example":"T0345246801","description":"ISWC for the composition when available."},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"playback_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri","description":"Public URL returned for this resource or action."},"preview_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","format":"uri","description":"Public URL returned for this resource or action."},"documents_requested":{"type":"boolean","example":false,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Track object returned by the public organization API."},"TrackUploadStatus":{"description":"Current state of a resumable track upload. Completed uploads include the audio_file_id required by track create and update requests.","oneOf":[{"type":"object","additionalProperties":false,"required":["success","complete","upload_session_id","state","received_chunks","total_chunks","expires_at"],"properties":{"success":{"type":"boolean","const":true},"complete":{"type":"boolean","const":false},"upload_session_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$"},"state":{"type":"string","enum":["receiving","assembling"]},"received_chunks":{"type":"array","items":{"type":"integer","minimum":0}},"total_chunks":{"type":"integer","minimum":1,"maximum":64},"expires_at":{"type":"string","format":"date-time"},"message":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["success","complete","upload_session_id","audio_file_id","file_name","original","links","extensions","duration","mime_type","checksum"],"properties":{"success":{"type":"boolean","const":true},"complete":{"type":"boolean","const":true},"upload_session_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$"},"audio_file_id":{"type":"string","description":"Temporary audio reference to pass when creating or updating a track."},"file_name":{"type":"string"},"original":{"type":"string"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"extensions":{"type":"object","additionalProperties":false,"required":["input","output"],"properties":{"input":{"type":"string"},"output":{"type":"string"}}},"duration":{"type":["integer","null"],"minimum":0},"mime_type":{"type":["string","null"]},"checksum":{"type":["string","null"]}}}]},"RevenueSplit":{"type":"object","additionalProperties":false,"required":["split_id","title","percentage","locked"],"properties":{"split_id":{"type":"string","example":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","format":"uuid","description":"Stable public split reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas Producer Share","description":"Catalog or content title shown in the dashboard and API responses."},"percentage":{"type":"integer","example":25,"description":"Revenue split percentage assigned to this beneficiary."},"start_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for start."},"end_date":{"description":"Calendar date for end.","type":["string","null"],"format":"date"},"locked":{"type":"boolean","example":false,"description":"Whether the split, role, or configuration is locked from further editing in its current state."},"beneficiary":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this revenuesplit."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account or invitation."}},"description":"User or collaborator receiving the revenue split share."},"creator":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this revenuesplit."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account or invitation."}},"description":"User summary for the person who created the record."},"releases":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}}},"description":"Releases visible for the current organization and permission scope."},"tracks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."}}},"description":"Tracks included in the release or returned by the catalog query."}},"description":"RevenueSplit object returned by the public organization API."},"Member":{"type":"object","additionalProperties":false,"properties":{"member_id":{"type":"string","example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","format":"uuid","description":"Stable public member reference for member-management endpoints. Store and use member_id when reading, updating, suspending, unsuspending, or removing a team member."},"first_name":{"type":"string","example":"Eli","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Brooks","description":"Family name for the user or member profile."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this member."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account or invitation."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"role":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this member."}},"description":"Role assigned to the user or member, including its public role reference and display name when expanded."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"invited_at":{"type":"string","example":"2026-07-01T12:00:00+00:00","format":"date-time","description":"Timestamp for when invited occurred, formatted as ISO 8601 when available."},"accepted_at":{"type":"string","example":"2026-07-02T09:05:00+00:00","format":"date-time","description":"Timestamp for when accepted occurred, formatted as ISO 8601 when available."}},"description":"Member object returned by the public organization API.","required":["member_id","name","email","status"]},"MemberRole":{"type":"object","additionalProperties":false,"required":["role_id","name","protected","permissions"],"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this memberrole."},"preset":{"type":"string","example":"catalog_manager","description":"Optional role template used to seed permissions before custom role edits are applied."},"protected":{"type":"boolean","example":false,"description":"Whether the role or setting is protected from organization-level edits."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."}},"description":"MemberRole object returned by the public organization API."},"Subscription":{"type":"object","additionalProperties":false,"required":["subscription_id","is_active","package","amount","total_paid_amount","gateway"],"properties":{"subscription_id":{"type":"string","example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","format":"uuid","description":"Stable public subscription reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"is_active":{"type":"boolean","example":true,"description":"Whether the subscription, plan, add-on, or resource is currently active."},"package":{"type":"object","additionalProperties":true,"properties":{"package_id":{"type":"string","example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","format":"uuid","description":"Stable public package reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Growth Distribution Monthly","description":"Display name for this subscription."},"type":{"type":"string","example":"membership","description":"Public type or role value for this item."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"price":{"type":"integer","example":49,"description":"price for package."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"royalty_percentage":{"type":"integer","example":85,"description":"royalty percentage for package."},"artist_profile_limit":{"type":"integer","example":25,"description":"artist profile limit for package."},"release_limit":{"type":"integer","example":50,"description":"release limit for package."},"release_limit_cycle":{"type":"string","example":"monthly","description":"release limit cycle for package."},"feature_list":{"type":"array","items":{"type":"string","example":"Unlimited team members"},"description":"feature list for package."}},"description":"Membership package attached to the subscription or checkout."},"subscribed_at":{"type":"string","example":"2026-06-01T09:00:00+00:00","format":"date-time","description":"Timestamp for when subscribed occurred, formatted as ISO 8601 when available."},"next_payment":{"type":"string","example":"2026-08-01T09:00:00+00:00","format":"date-time","description":"Next scheduled payment date for the subscription when available."},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"total_paid_amount":{"type":"integer","example":98,"description":"Monetary amount in the currency shown on the same object."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]}},"description":"Subscription object returned by the public organization API."},"Checkout":{"type":"object","additionalProperties":false,"required":["checkout_id","gateway","status"],"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"embedded_checkout_token":{"type":"string","example":"docs_invalid_embedded_checkout_token","description":"Short-lived embedded checkout token. Treat this value as sensitive payment data and never log it or expose it in support tickets.","format":"password","x-sensitive":true},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"description":"Checkout object returned by the public organization API."},"Smartlink":{"type":"object","additionalProperties":false,"required":["smartlink_id","slug","title","status","destinations"],"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"slug":{"type":"string","example":"nova-vale-midnight-atlas","description":"URL-safe slug used for public links or add-on references."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"public_url":{"type":"string","example":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","format":"uri","description":"Public URL returned for this resource or action."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."},"clicks":{"type":"integer","example":1840,"description":"Number of recorded smartlink clicks for the selected period or destination."},"conversion_rate":{"type":"number","example":0.18,"description":"Percentage of visitors who clicked through or completed the measured smartlink action."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Smartlink object returned by the public organization API."}}},"paths":{"/api/v1/ddex/standards":{"get":{"tags":["DDEX"],"summary":"Get DDEX compatibility matrix","operationId":"getDdexStandards","description":"Read the exact ERN, Release Profile, AVS, choreography, feature, migration, schema-asset, and staging simulation policy supported by the Enterprise Delivery API.","responses":{"200":{"$ref":"#/components/responses/DdexStandardsResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/sender-identities":{"get":{"tags":["DDEX"],"summary":"List DDEX sender identities","operationId":"listDdexSenderIdentities","description":"List tenant-owned DPID sender identities and their attestation state before configuring a versioned partner connection.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"$ref":"#/components/responses/DdexSenderIdentityCollection"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["DDEX"],"summary":"Create DDEX sender identity","operationId":"createDdexSenderIdentity","description":"Attest and register an organization DPID sender identity for later use by sandbox or approved live partner connections.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","dpid","attestation"],"properties":{"name":{"type":"string","minLength":1,"maxLength":150},"dpid":{"type":"string","maxLength":100,"description":"Valid PADPIDA identifier in canonical or human-readable hyphenated form."},"attestation":{"type":"boolean","const":true,"description":"Must be true to attest that the organization controls this DPID."}}},"example":{"name":"Example Records","dpid":"PA-DPIDA-2026073001-N","attestation":true}}}},"responses":{"201":{"$ref":"#/components/responses/DdexSenderIdentityResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/connections":{"get":{"tags":["DDEX"],"summary":"List DDEX partner connections","operationId":"listDdexConnections","description":"List versioned partner capability profiles, commercial routes, exact standards, environments, and current health without returning secrets.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"$ref":"#/components/responses/DdexConnectionCollection"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["DDEX"],"summary":"Create DDEX partner connection","operationId":"createDdexConnection","description":"Create a locked draft connection that pins commercial route, DPIDs, ERN, profile, AVS, choreography, ownership, and partner contract rules. Creation never enables transport.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","partner_name","integration_owner_reference","commercial_route","direction","environment","remote_dpid","ern_version","release_profile","avs_version","choreography","hosting_mode","auth_type"],"properties":{"name":{"type":"string","minLength":1,"maxLength":150},"partner_name":{"type":"string","minLength":1,"maxLength":150},"sender_identity_reference":{"type":"string","format":"uuid","description":"Required for direct_partner. Omit for spacemedia_delivery_deal, which always uses the SpaceMedia platform DPID."},"integration_owner_reference":{"type":"string","format":"uuid"},"commercial_route":{"type":"string","enum":["spacemedia_delivery_deal","direct_partner"]},"direction":{"type":"string","enum":["outbound","inbound","bidirectional"]},"environment":{"type":"string","enum":["sandbox","live"]},"remote_dpid":{"type":"string","minLength":1,"maxLength":100,"description":"Partner DPID in canonical no-hyphen form or human-readable hyphenated form. XML always uses the canonical no-hyphen form."},"ern_version":{"type":"string","enum":["4.3.0","4.3.1","4.3.2"]},"release_profile":{"type":"string","enum":["Audio","SimpleAudioSingle"]},"avs_version":{"type":"string","enum":["011"]},"choreography":{"type":"string","enum":["web_service_1_8","cloud_storage_1_8_1"]},"hosting_mode":{"type":"string","enum":["spacemedia_managed","partner_managed"]},"auth_type":{"type":"string","enum":["basic","bearer","sftp_password","sftp_key"]},"endpoint_url":{"type":["string","null"],"format":"uri","maxLength":2048},"agreement_reference":{"type":["string","null"],"maxLength":191},"supersedes_reference":{"type":["string","null"],"format":"uuid"},"capabilities":{"type":["array","null"],"items":{"type":"string"},"uniqueItems":true},"contract_rules":{"type":["object","null"],"additionalProperties":true},"credentials":{"type":["object","null"],"additionalProperties":true,"writeOnly":true,"description":"Partner credentials accepted for storage but never returned by the API."}}},"example":{"name":"Partner sandbox","partner_name":"Example DSP","sender_identity_reference":"4a077d69-e377-43cd-9abb-43f68cd73da1","integration_owner_reference":"8370fe8c-b8ac-4a3c-a7cd-b91f1bf1177b","commercial_route":"direct_partner","direction":"outbound","environment":"sandbox","remote_dpid":"PA-DPIDA-2026073002-N","ern_version":"4.3.2","release_profile":"Audio","avs_version":"011","choreography":"web_service_1_8","hosting_mode":"partner_managed","auth_type":"bearer","endpoint_url":"https://partner.example/ddex","capabilities":["insert","update","global_takedown"],"credentials":{"bearer_token":"replace-with-partner-token"}}}}},"responses":{"201":{"description":"Versioned DDEX partner connection created without returning stored credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdexConnectionResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/connections/{reference}/activation-request":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["DDEX"],"summary":"Request DDEX connection activation","operationId":"requestDdexConnectionActivation","description":"Submit a locked draft connection for SpaceMedia connection activation review and sandbox conformance testing. This is operational connection review, not SpaceMedia release review. No partner certificate is required. Transport remains disabled until review, conformance, health, platform, contract, and environment gates pass.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"$ref":"#/components/responses/DdexConnectionResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/connections/{reference}/rotate-secret":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["DDEX"],"summary":"Rotate DDEX connection secret","operationId":"updateDdexConnectionSecret","description":"Replace encrypted partner credentials without returning the stored values and require a new health check before operational use.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credentials"],"properties":{"credentials":{"type":"object","additionalProperties":true}}},"example":{"credentials":{"bearer_token":"replace-with-new-partner-token"}}}}},"responses":{"200":{"description":"DDEX partner credentials replaced without returning the stored values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdexConnectionResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/connections/{reference}/health-check":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["DDEX"],"summary":"Start DDEX connection health check","operationId":"startDdexConnectionHealthCheck","description":"Check credentials, endpoint configuration, licensed schema assets, live transport gates, and connection readiness without exposing secrets. Staging sandbox checks are isolated and report whether simulation or an external probe was used.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"$ref":"#/components/responses/DdexConnectionHealthAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/connections/{reference}/feed":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["DDEX"],"summary":"Get DDEX Web Service feed","operationId":"getDdexWebServiceFeed","description":"Read the authenticated Atom feed of current available messages for a Web Service 1.8 sender connection and follow payload links.","responses":{"200":{"description":"The current authenticated Atom feed was returned with at most one current message per release.","content":{"application/atom+xml":{"schema":{"type":"string"},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><feed xmlns=\"http://www.w3.org/2005/Atom\"><id>urn:uuid:3bc1f628-60af-4db2-b984-321c1525df20</id><title>Example DSP DDEX feed</title><updated>2026-07-30T15:45:00Z</updated><entry><id>urn:uuid:45be9e79-f39e-4cf9-bfc8-bf9f10481da6</id><title>PA-DPIDA-2026073001-N; 45be9e79-f39e-4cf9-bfc8-bf9f10481da6; 2026-07-30</title><updated>2026-07-30T15:45:00Z</updated><link rel=\"alternate\" type=\"application/xml\" href=\"https://staging.spacemedia.uk/api/v1/ddex/messages/45be9e79-f39e-4cf9-bfc8-bf9f10481da6/payload\"/></entry></feed>"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/deal-profiles":{"get":{"tags":["DDEX"],"summary":"List DDEX deal profiles","operationId":"listDdexDealProfiles","description":"List explicit commercial models, use types, territories, validity windows, and partner terms available to DDEX operations.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"$ref":"#/components/responses/DdexDealProfileCollection"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["DDEX"],"summary":"Create DDEX deal profile","operationId":"createDdexDealProfile","description":"Create a reusable deal profile with explicit use types, territories, validity periods, commercial model, and contract terms.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","commercial_model","use_types","territories"],"properties":{"name":{"type":"string","minLength":1,"maxLength":150},"commercial_model":{"type":"string","minLength":1,"maxLength":100},"use_types":{"type":"array","minItems":1,"items":{"type":"string","maxLength":100}},"territories":{"type":"array","minItems":1,"items":{"type":"string","maxLength":3}},"valid_from":{"type":["string","null"],"description":"ISO 8601 date or date-time when the deal becomes valid."},"valid_until":{"type":["string","null"],"description":"ISO 8601 date or date-time after valid_from when the deal ends."},"terms":{"type":["object","null"],"additionalProperties":true}}},"example":{"name":"Premium subscription","commercial_model":"SubscriptionModel","use_types":["OnDemandStream"],"territories":["GB","US","DE"],"valid_from":"2026-08-01","terms":{"usage":"commercial"}}}}},"responses":{"201":{"$ref":"#/components/responses/DdexDealProfileResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/uploads":{"post":{"tags":["DDEX"],"summary":"Upload native DDEX message","operationId":"uploadNativeDdexMessage","description":"Accept a native ERN message for secure parsing and immutable preservation before validation, relay, export, or create-only import.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdexOperationInput"}}}},"responses":{"202":{"$ref":"#/components/responses/DdexAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/validations":{"post":{"tags":["DDEX"],"summary":"Validate DDEX operation","operationId":"validateDdexOperation","description":"Run secure XML, DDEX, catalog, contract, transport, review, and state checks without transmitting the resulting package.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdexOperationInput"}}}},"responses":{"202":{"$ref":"#/components/responses/DdexAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/exports":{"post":{"tags":["DDEX"],"summary":"Create DDEX export","operationId":"createDdexExport","description":"Snapshot a SpaceMedia release or preserve native ERN XML, validate it, and create a downloadable immutable package without transmission.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdexOperationInput"}}}},"responses":{"202":{"$ref":"#/components/responses/DdexAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/deliveries":{"post":{"tags":["DDEX"],"summary":"Create DDEX delivery","operationId":"createDdexDelivery","description":"Validate, package, and queue delivery for a release or native ERN. SpaceMedia delivery deals wait for SpaceMedia review; direct partners do not. Staging sandbox transport is simulated and never contacts a partner endpoint.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdexOperationInput"}}}},"responses":{"202":{"$ref":"#/components/responses/DdexAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/batches":{"get":{"tags":["DDEX"],"summary":"List DDEX delivery batches","operationId":"listDdexBatches","description":"List Cloud Storage 1.8.1 batches, message counts, completion state, and immutable manifest checksum for the organization.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"$ref":"#/components/responses/DdexBatchCollection"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["DDEX"],"summary":"Create DDEX delivery batch","operationId":"createDdexBatch","description":"Group eligible messages for one Cloud Storage 1.8.1 connection and publish an immutable batch manifest after all message artifacts.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connection_reference","message_references"],"properties":{"connection_reference":{"type":"string","format":"uuid"},"message_references":{"type":"array","minItems":1,"maxItems":1000,"uniqueItems":true,"items":{"type":"string","format":"uuid"}}}},"example":{"connection_reference":"3bc1f628-60af-4db2-b984-321c1525df20","message_references":["45be9e79-f39e-4cf9-bfc8-bf9f10481da6","1f4e5664-881e-4eca-bcb3-97f10c53b7ca"]}}}},"responses":{"202":{"$ref":"#/components/responses/DdexBatchAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/imports":{"get":{"tags":["DDEX"],"summary":"List native DDEX imports","operationId":"listDdexImports","description":"List atomic create-only inbound import requests, preserved source messages, unmapped fields, and resulting draft release references.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"$ref":"#/components/responses/DdexImportCollection"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["DDEX"],"summary":"Create native DDEX import","operationId":"createDdexImport","description":"Validate a native inbound ERN under an inbound connection and stage an atomic create-only draft import owned by the configured integration user.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["connection_reference","native_xml","action"],"properties":{"connection_reference":{"type":"string","format":"uuid"},"native_xml":{"type":"string","maxLength":26214400,"description":"Secure, well-formed native ERN XML up to 25 MiB."},"action":{"type":"string","enum":["insert"]},"metadata_overlay":{"type":["object","null"],"additionalProperties":true}}},"example":{"connection_reference":"3bc1f628-60af-4db2-b984-321c1525df20","native_xml":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><ern:NewReleaseMessage xmlns:ern=\"http://ddex.net/xml/ern/43\">...</ern:NewReleaseMessage>","action":"insert"}}}},"responses":{"202":{"$ref":"#/components/responses/DdexImportAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/imports/{reference}":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["DDEX"],"summary":"Get native DDEX import","operationId":"getDdexImport","description":"Get the canonical status, preserved source-message reference, unmapped fields, and created draft release references for one atomic inbound import.","responses":{"200":{"$ref":"#/components/responses/DdexImportResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/messages":{"get":{"tags":["DDEX"],"summary":"List DDEX message operations","operationId":"listDdexMessages","description":"List immutable message operations and their separate control, SpaceMedia review, transport, partner, and webhook delivery states.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"status","in":"query","required":false,"description":"Return only messages in the exact control-plane status.","schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DdexMessageCollection"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/messages/{reference}":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["DDEX"],"summary":"Get DDEX message operation","operationId":"getDdexMessage","description":"Get canonical current state, immutable hashes, validation findings, acknowledgement metadata, and authorized payload link for one message.","responses":{"200":{"$ref":"#/components/responses/DdexMessageResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"tags":["DDEX"],"summary":"Confirm DDEX message claim","operationId":"confirmDdexMessageClaim","description":"Confirm that the recipient claimed the currently available message. Claim does not mean the release is live or fully processed.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"$ref":"#/components/responses/DdexMessageResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/messages/{reference}/payload":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["DDEX"],"summary":"Download DDEX XML payload","operationId":"downloadDdexPayload","description":"Download the immutable generated or original native XML payload with private caching, content-type protection, and SHA-256 digest.","responses":{"200":{"description":"The authorized immutable DDEX XML payload was returned with its checksum.","content":{"application/xml":{"schema":{"type":"string"},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><ern:NewReleaseMessage xmlns:ern=\"http://ddex.net/xml/ern/43\"><MessageHeader>...</MessageHeader><ResourceList>...</ResourceList><ReleaseList>...</ReleaseList><DealList>...</DealList></ern:NewReleaseMessage>"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/messages/{reference}/resources/{resourceReference}":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"resourceReference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["DDEX"],"summary":"Download DDEX delivery resource","operationId":"downloadDdexResource","description":"Stream an authorized audio resource referenced by a generated ERN message. Supports byte ranges, immutable SHA-256 digest and ETag headers, and returns 404 after the message is superseded.","parameters":[{"name":"Range","in":"header","required":false,"schema":{"type":"string","example":"bytes=0-1048575"},"description":"Optional RFC 7233 single byte range."}],"responses":{"200":{"description":"The complete authorized resource stream.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"The requested resource byte range.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"416":{"description":"The requested byte range is invalid or outside the resource."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/messages/{reference}/validation-report":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["DDEX"],"summary":"Download DDEX validation report","operationId":"downloadDdexValidationReport","description":"Download the explainable validation report with stable findings, locations, remediation, retryability, and support correlation key.","responses":{"200":{"$ref":"#/components/responses/DdexValidationReport"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/messages/{reference}/retry":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["DDEX"],"summary":"Retry DDEX message operation","operationId":"startDdexMessageRetry","description":"Revalidate a blocked or failed message and queue it only when every current finding is non-blocking and the failure is retryable.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"$ref":"#/components/responses/DdexAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/messages/{reference}/cancel":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["DDEX"],"summary":"Cancel DDEX message operation","operationId":"cancelDdexMessage","description":"Cancel work that has not been claimed by the partner. Claimed, acknowledged, or terminal message operations cannot be cancelled.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"$ref":"#/components/responses/DdexMessageResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ddex/messages/{reference}/acknowledgements":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["DDEX"],"summary":"Create DDEX acknowledgement","operationId":"createDdexAcknowledgement","description":"Store an acknowledgement or processing-status payload separately from claim state while preserving the exact partner payload and checksum.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","status","payload"],"properties":{"type":{"type":"string","enum":["acknowledgement","processing_status"]},"status":{"type":"string","enum":["accepted","rejected","processing","live","takedown_complete"]},"partner_reference":{"type":"string","maxLength":191},"payload":{"type":"string","maxLength":26214400,"description":"Secure, well-formed acknowledgement XML up to 25 MiB."}}},"example":{"type":"acknowledgement","status":"accepted","partner_reference":"partner-ack-1042","payload":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><Acknowledgement>...</Acknowledgement>"}}}},"responses":{"202":{"$ref":"#/components/responses/DdexAcknowledgementAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/webhooks":{"get":{"tags":["Enterprise Webhooks"],"summary":"List enterprise webhooks","operationId":"listEnterpriseWebhooks","description":"List organization webhook subscriptions, event filters, endpoint state, and secret-rotation timestamp without returning signing secrets.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"$ref":"#/components/responses/EnterpriseWebhookCollection"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Enterprise Webhooks"],"summary":"Create enterprise webhook","operationId":"createEnterpriseWebhook","description":"Create an HTTPS webhook subscription with DDEX event filters and return its HMAC signing secret exactly once.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","endpoint_url","events"],"properties":{"name":{"type":"string","minLength":1,"maxLength":150},"endpoint_url":{"type":"string","format":"uri","pattern":"^https://","maxLength":2048},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["ddex.delivery.status_changed","ddex.delivery.blocked","ddex.delivery.acknowledged","ddex.delivery.rejected","ddex.delivery.failed","ddex.import.completed","ddex.import.failed","ddex.connection.degraded"]}}}},"example":{"name":"DDEX operations","endpoint_url":"https://integrator.example/webhooks/spacemedia","events":["ddex.delivery.status_changed","ddex.delivery.failed","ddex.import.completed"]}}}},"responses":{"201":{"description":"Webhook subscription created. The signing secret is returned only in this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseWebhookSecretResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/webhooks/{reference}":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Enterprise Webhooks"],"summary":"Update enterprise webhook","operationId":"updateEnterpriseWebhook","description":"Update the webhook name, HTTPS endpoint, event filters, or active state. Set active to false to pause delivery without deleting audit history.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":150},"endpoint_url":{"type":"string","format":"uri","pattern":"^https://","maxLength":2048},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["ddex.delivery.status_changed","ddex.delivery.blocked","ddex.delivery.acknowledged","ddex.delivery.rejected","ddex.delivery.failed","ddex.import.completed","ddex.import.failed","ddex.connection.degraded"]}},"active":{"type":"boolean"}}},"example":{"active":false}}}},"responses":{"200":{"description":"Webhook subscription updated.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EnterpriseWebhookSubscription"}}},"example":{"data":{"reference":"9f6529b3-218a-478f-a074-0830165889c5","name":"DDEX operations","endpoint_url":"https://integrator.example/webhooks/spacemedia","events":["ddex.delivery.status_changed","ddex.delivery.failed"],"active":false,"secret_configured":true,"secret_rotated_at":"2026-07-30T15:40:00Z","previous_secret_valid_until":null,"created_at":"2026-07-30T15:40:00Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"tags":["Enterprise Webhooks"],"summary":"Delete enterprise webhook","operationId":"deleteEnterpriseWebhook","description":"Permanently remove a webhook subscription and its delivery history. Pause the subscription instead when audit history must be retained.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Webhook subscription and its delivery history deleted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["success","deleted","reference"],"properties":{"success":{"type":"boolean","const":true},"deleted":{"type":"boolean","const":true},"reference":{"type":"string","format":"uuid"}}},"example":{"success":true,"deleted":true,"reference":"9f6529b3-218a-478f-a074-0830165889c5"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/webhooks/{reference}/rotate-secret":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Enterprise Webhooks"],"summary":"Rotate webhook signing secret","operationId":"updateEnterpriseWebhookSecret","description":"Replace a webhook HMAC signing secret and return the new value exactly once for secure receiver configuration.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Webhook signing secret rotated. The replacement secret is returned only in this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseWebhookSecretResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/webhooks/{reference}/test":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Enterprise Webhooks"],"summary":"Create test webhook delivery","operationId":"createEnterpriseWebhookTest","description":"Queue a signed test event through the normal webhook delivery, retry, logging, and replay-protection contract.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"$ref":"#/components/responses/WebhookDeliveryAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/webhooks/{reference}/deliveries":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Enterprise Webhooks"],"summary":"List webhook delivery attempts","operationId":"listEnterpriseWebhookDeliveries","description":"List event delivery references, attempts, response status, retry timing, and final delivery state for one subscription.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"$ref":"#/components/responses/EnterpriseWebhookDeliveryCollection"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/webhooks/{reference}/deliveries/{deliveryReference}/replay":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"deliveryReference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Enterprise Webhooks"],"summary":"Replay enterprise webhook delivery","operationId":"createEnterpriseWebhookReplay","description":"Create a new signed delivery attempt from a prior event while preserving the original delivery reference for audit and deduplication.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"$ref":"#/components/responses/WebhookDeliveryAccepted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/account-settings/labels":{"post":{"tags":["Account Settings"],"summary":"Create Account Label","operationId":"createAccountLabel","description":"Create Account Label. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Create Account Label succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Label created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"label_id":{"type":"string","example":"7da47646-3011-43f8-b497-8a5b1bc2d546","format":"uuid","description":"Stable public label reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Night Shift Records","description":"Display name for this data."},"releases_count":{"type":"integer","example":18,"description":"Number of releases currently associated with the artist."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Label created.","data":{"label_id":"7da47646-3011-43f8-b497-8a5b1bc2d546","name":"Night Shift Records","releases_count":18,"created_at":"2026-07-04T09:30:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"name":["The name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Night Shift Records","description":"Display name for this request body."}},"required":["name"]},"example":{"name":"Night Shift Records"}}}}}},"/api/v1/account-settings/me":{"get":{"tags":["Account Settings"],"summary":"View Current Account Settings","operationId":"getCurrentAccountSettings","description":"View Current Account Settings. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"View Current Account Settings succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"profile":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this profile."},"full_name":{"type":"string","example":"Maya Chen","description":"Full display name assembled from the account profile fields."},"first_name":{"type":"string","example":"Maya","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Chen","description":"Family name for the user or member profile."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"phone":{"type":"string","example":"+442071838750","description":"Phone number on the account profile when provided."},"language":{"type":"string","example":"en","description":"Primary language value used for profile, release, or track metadata."},"country":{"type":"string","example":"United Kingdom","description":"Country associated with the user, artist, or organization record."},"profile_photo":{"type":"string","example":"https://assets.spacemedia-docs.invalid/users/maya-chen/profile-photo.webp","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"verified":{"type":"boolean","example":true,"description":"Whether the account email or identity state is verified."},"email_verified_at":{"type":"string","example":"2026-06-25T08:15:00+00:00","format":"date-time","description":"Timestamp for when email verified occurred, formatted as ISO 8601 when available."},"last_login_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last login occurred, formatted as ISO 8601 when available."},"invitation_status":{"type":"string","example":"accepted","description":"Invitation lifecycle status, such as pending or accepted."},"is_invited":{"type":"boolean","example":false,"description":"Whether this user was created through an organization invitation."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this roles."}}},"description":"Roles assigned to the user or member within the organization."},"organization_name":{"type":"string","example":"Northstar Distribution","description":"Display name of the organization that owns the record."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Profile object for the account, theme, email theme, or member being returned."},"labels":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"label_id":{"type":"string","example":"7da47646-3011-43f8-b497-8a5b1bc2d546","format":"uuid","description":"Stable public label reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Night Shift Records","description":"Display name for this labels."},"releases_count":{"type":"integer","example":18,"description":"Number of releases currently associated with the artist."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."}}},"description":"Custom labels available to the authenticated account or organization."},"artist_types":{"type":"array","items":{"type":"string","example":"Primary Artist"},"description":"Artist type options available for catalog metadata forms."},"genres":{"type":"array","items":{"type":"string","example":"Electronic"},"description":"Genre options available for release and track metadata forms."},"languages":{"type":"array","items":{"type":"string","example":"English"},"description":"Language options available for release and track metadata forms."},"notification_preferences":{"type":"object","additionalProperties":true,"properties":{"release_status":{"type":"boolean","example":true,"description":"Current release status shown to the organization."},"payment_updates":{"type":"boolean","example":true,"description":"Whether the user receives payment, invoice, checkout, and billing status notifications."},"product_updates":{"type":"boolean","example":false,"description":"Whether the user receives product, add-on, and feature update notifications."}},"description":"Notification settings currently stored for the authenticated account."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"profile":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","full_name":"Maya Chen","first_name":"Maya","last_name":"Chen","email":"maya.chen@northstar-distribution.co.uk","phone":"+442071838750","language":"en","country":"United Kingdom","profile_photo":"https://assets.spacemedia-docs.invalid/users/maya-chen/profile-photo.webp","verified":true,"email_verified_at":"2026-06-25T08:15:00+00:00","last_login_at":"2026-07-04T10:15:00+00:00","invitation_status":"accepted","is_invited":false,"is_suspended":false,"roles":[{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"}],"organization_name":"Northstar Distribution","created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"},"labels":[{"label_id":"7da47646-3011-43f8-b497-8a5b1bc2d546","name":"Night Shift Records","releases_count":18,"created_at":"2026-07-04T09:30:00+00:00"}],"artist_types":["Primary Artist","Featured Artist","Composer","Producer"],"genres":["Electronic","Ambient","Pop"],"languages":["English","German","Spanish"],"notification_preferences":{"release_status":true,"payment_updates":true,"product_updates":false}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/account-settings/notifications":{"post":{"tags":["Account Settings"],"summary":"Update Notification Preferences","operationId":"updateNotificationPreferences","description":"Update Notification Preferences. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Update Notification Preferences succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Notification preferences updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Notification preferences updated."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for release_status. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"release_status":["Choose a supported status value for this endpoint."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"release_status":{"type":"boolean","example":true,"description":"Current release status shown to the organization."},"payment_updates":{"type":"boolean","example":true,"description":"Whether the user receives payment, invoice, checkout, and billing status notifications."},"product_updates":{"type":"boolean","example":false,"description":"Whether the user receives product, add-on, and feature update notifications."}},"minProperties":1,"description":"Send at least one notification preference to update."},"example":{"release_status":true,"payment_updates":true,"product_updates":false}}}}}},"/api/v1/account-settings/personal-information":{"post":{"tags":["Account Settings"],"summary":"Update Personal Information","operationId":"updatePersonalInformation","description":"Update Personal Information. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Update Personal Information succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Personal information updated successfully.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Personal information updated successfully."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for first_name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"first_name":["The first name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"first_name":{"type":"string","example":"Maya","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Chen","description":"Family name for the user or member profile."},"phone":{"type":"string","example":"+442071838750","description":"Phone number on the account profile when provided."},"country":{"type":"string","example":"United Kingdom","description":"Country associated with the user, artist, or organization record."},"language":{"type":"string","example":"en","description":"Primary language value used for profile, release, or track metadata."}},"required":["first_name","last_name"]},"example":{"first_name":"Maya","last_name":"Chen","phone":"+442071838750","country":"United Kingdom","language":"en"}}}}}},"/api/v1/account-settings/sessions":{"get":{"tags":["Account Settings"],"summary":"List Account Sessions","operationId":"listAccountSessions","description":"List Account Sessions. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"List Account Sessions succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"session_id":{"type":"string","example":"6c53fe6af9bb6ec0487d27d0a0238edb7ad3ad9ad0e7a849a474efc53ea13f71","description":"Opaque session revocation reference returned by the session list. Use it only with the delete-session endpoint and do not parse it for user, device, or storage details.","pattern":"^[a-f0-9]{64}$","minLength":64,"maxLength":64},"device":{"type":"string","example":"Chrome on macOS","description":"Browser, device, or client name associated with an active session."},"ip":{"type":"string","example":"203.0.113.10","description":"IP address associated with an active session when available to the account."},"last_active_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last active occurred, formatted as ISO 8601 when available."},"current":{"type":"boolean","example":true,"description":"Whether the session or setting refers to the current authenticated request."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"session_id":"6c53fe6af9bb6ec0487d27d0a0238edb7ad3ad9ad0e7a849a474efc53ea13f71","device":"Chrome on macOS","ip":"203.0.113.10","last_active_at":"2026-07-04T10:15:00+00:00","current":true}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/account-settings/sessions/{session_id}":{"delete":{"tags":["Account Settings"],"summary":"Delete Account Session","operationId":"deleteAccountSession","description":"Delete Account Session. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It removes, revokes, or cancels the target when permissions and resource state allow it, then returns a confirmation or policy error.","parameters":[{"name":"session_id","in":"path","required":true,"description":"Opaque session revocation reference returned by GET /api/v1/account-settings/sessions.","schema":{"type":"string","pattern":"^[a-f0-9]{64}$","minLength":64,"maxLength":64},"example":"6c53fe6af9bb6ec0487d27d0a0238edb7ad3ad9ad0e7a849a474efc53ea13f71"}],"responses":{"200":{"description":"Delete Account Session succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Session deleted.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Session deleted."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/addons/{addon_slug}/{addon_version}/activate":{"post":{"tags":["Add-Ons"],"summary":"Activate Add-On","operationId":"activateAddon","description":"Activate Add-On. Use it to install, activate, deactivate, uninstall, and purchase organization add-ons that are visible to the caller through normal account permissions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"addon_slug","in":"path","required":true,"description":"Add-on slug, for example release-smartlinks or members-management.","schema":{"type":"string","example":"release-smartlinks"},"example":"release-smartlinks"},{"name":"addon_version","in":"path","required":true,"description":"Add-on version available to the organization.","schema":{"type":"string","example":"1.3.0"},"example":"1.3.0"}],"responses":{"200":{"description":"Activate Add-On succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Add-on activate completed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"license_id":{"type":"string","example":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","format":"uuid","description":"Stable public license reference. Use this value in related endpoint paths and request bodies."},"addon_slug":{"type":"string","example":"release-smartlinks","description":"Public slug for the add-on, used in add-on checkout and lifecycle endpoint paths."},"addon_version":{"type":"string","example":"1.3.0","description":"Version of the add-on being purchased or activated, matching a version available to the organization."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"flow":{"type":"string","example":"organization_install","description":"Checkout or setup flow type returned to help the client choose hosted redirect or embedded handling."},"installed":{"type":"boolean","example":true,"description":"Whether the add-on is currently installed for the organization."},"activated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when activated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Add-on activate completed.","data":{"license_id":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","addon_slug":"release-smartlinks","addon_version":"1.3.0","status":"active","flow":"organization_install","installed":true,"activated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/addons/{addon_slug}/{addon_version}/deactivate":{"post":{"tags":["Add-Ons"],"summary":"Deactivate Add-On","operationId":"deactivateAddon","description":"Deactivate Add-On. Use it to install, activate, deactivate, uninstall, and purchase organization add-ons that are visible to the caller through normal account permissions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"addon_slug","in":"path","required":true,"description":"Add-on slug, for example release-smartlinks or members-management.","schema":{"type":"string","example":"release-smartlinks"},"example":"release-smartlinks"},{"name":"addon_version","in":"path","required":true,"description":"Add-on version available to the organization.","schema":{"type":"string","example":"1.3.0"},"example":"1.3.0"}],"responses":{"200":{"description":"Deactivate Add-On succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Add-on deactivate completed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"license_id":{"type":"string","example":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","format":"uuid","description":"Stable public license reference. Use this value in related endpoint paths and request bodies."},"addon_slug":{"type":"string","example":"release-smartlinks","description":"Public slug for the add-on, used in add-on checkout and lifecycle endpoint paths."},"addon_version":{"type":"string","example":"1.3.0","description":"Version of the add-on being purchased or activated, matching a version available to the organization."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"flow":{"type":"string","example":"organization_install","description":"Checkout or setup flow type returned to help the client choose hosted redirect or embedded handling."},"installed":{"type":"boolean","example":true,"description":"Whether the add-on is currently installed for the organization."},"activated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when activated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Add-on deactivate completed.","data":{"license_id":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","addon_slug":"release-smartlinks","addon_version":"1.3.0","status":"active","flow":"organization_install","installed":true,"activated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/addons/{addon_slug}/{addon_version}/install":{"post":{"tags":["Add-Ons"],"summary":"Install Add-On","operationId":"installAddon","description":"Install Add-On. Use it to install, activate, deactivate, uninstall, and purchase organization add-ons that are visible to the caller through normal account permissions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"addon_slug","in":"path","required":true,"description":"Add-on slug, for example release-smartlinks or members-management.","schema":{"type":"string","example":"release-smartlinks"},"example":"release-smartlinks"},{"name":"addon_version","in":"path","required":true,"description":"Add-on version available to the organization.","schema":{"type":"string","example":"1.3.0"},"example":"1.3.0"}],"responses":{"200":{"description":"Install Add-On succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Add-on install completed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"license_id":{"type":"string","example":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","format":"uuid","description":"Stable public license reference. Use this value in related endpoint paths and request bodies."},"addon_slug":{"type":"string","example":"release-smartlinks","description":"Public slug for the add-on, used in add-on checkout and lifecycle endpoint paths."},"addon_version":{"type":"string","example":"1.3.0","description":"Version of the add-on being purchased or activated, matching a version available to the organization."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"flow":{"type":"string","example":"organization_install","description":"Checkout or setup flow type returned to help the client choose hosted redirect or embedded handling."},"installed":{"type":"boolean","example":true,"description":"Whether the add-on is currently installed for the organization."},"activated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when activated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Add-on install completed.","data":{"license_id":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","addon_slug":"release-smartlinks","addon_version":"1.3.0","status":"active","flow":"organization_install","installed":true,"activated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/addons/{addon_slug}/{addon_version}/uninstall":{"post":{"tags":["Add-Ons"],"summary":"Uninstall Add-On","operationId":"uninstallAddon","description":"Uninstall Add-On. Use it to install, activate, deactivate, uninstall, and purchase organization add-ons that are visible to the caller through normal account permissions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"addon_slug","in":"path","required":true,"description":"Add-on slug, for example release-smartlinks or members-management.","schema":{"type":"string","example":"release-smartlinks"},"example":"release-smartlinks"},{"name":"addon_version","in":"path","required":true,"description":"Add-on version available to the organization.","schema":{"type":"string","example":"1.3.0"},"example":"1.3.0"}],"responses":{"200":{"description":"Uninstall Add-On succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Add-on uninstall completed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"license_id":{"type":"string","example":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","format":"uuid","description":"Stable public license reference. Use this value in related endpoint paths and request bodies."},"addon_slug":{"type":"string","example":"release-smartlinks","description":"Public slug for the add-on, used in add-on checkout and lifecycle endpoint paths."},"addon_version":{"type":"string","example":"1.3.0","description":"Version of the add-on being purchased or activated, matching a version available to the organization."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"flow":{"type":"string","example":"organization_install","description":"Checkout or setup flow type returned to help the client choose hosted redirect or embedded handling."},"installed":{"type":"boolean","example":true,"description":"Whether the add-on is currently installed for the organization."},"activated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when activated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Add-on uninstall completed.","data":{"license_id":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","addon_slug":"release-smartlinks","addon_version":"1.3.0","status":"active","flow":"organization_install","installed":true,"activated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/addons/{addon_slug}/checkout":{"post":{"tags":["Add-Ons"],"summary":"Create Add-On Checkout","operationId":"createAddonCheckout","description":"Create a checkout for an organization add-on version and billing cycle. Store checkout_id locally and verify the checkout before enabling paid add-on behavior in your integration.","parameters":[{"name":"addon_slug","in":"path","required":true,"description":"Add-on slug, for example release-smartlinks or members-management.","schema":{"type":"string","example":"release-smartlinks"},"example":"release-smartlinks"}],"responses":{"200":{"description":"Create Add-On Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"license_id":{"type":"string","example":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","format":"uuid","description":"Stable public license reference. Use this value in related endpoint paths and request bodies."},"addon_slug":{"type":"string","example":"release-smartlinks","description":"Public slug for the add-on, used in add-on checkout and lifecycle endpoint paths."},"addon_version":{"type":"string","example":"1.3.0","description":"Version of the add-on being purchased or activated, matching a version available to the organization."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"flow":{"type":"string","example":"organization_install","description":"Checkout or setup flow type returned to help the client choose hosted redirect or embedded handling."},"installed":{"type":"boolean","example":true,"description":"Whether the add-on is currently installed for the organization."},"activated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when activated occurred, formatted as ISO 8601 when available."},"checkout":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"embedded_checkout_token":{"type":"string","example":"docs_invalid_embedded_checkout_token","description":"Short-lived embedded checkout token. Treat this value as sensitive payment data and never log it or expose it in support tickets.","format":"password","x-sensitive":true},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"description":"Checkout object containing the public checkout reference, gateway, status, and continuation fields."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"license_id":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","addon_slug":"release-smartlinks","addon_version":"1.3.0","status":"active","flow":"organization_install","installed":true,"activated_at":"2026-07-04T10:15:00+00:00","checkout":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"airwallex","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","embedded_checkout_token":"docs_invalid_embedded_checkout_token","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for addon_version. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"addon_version":["The addon version field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"addon_version":{"type":"string","example":"1.3.0","description":"Version of the add-on being purchased or activated, matching a version available to the organization."},"cycle":{"type":"string","example":"monthly","description":"Billing cycle requested for the add-on checkout, such as monthly or yearly when both are offered."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/addons/release-smartlinks/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/addons/release-smartlinks/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["addon_version","gateway"]},"example":{"addon_version":"1.3.0","cycle":"monthly","gateway":"airwallex","success_url":"https://northstar-distribution.co.uk/addons/release-smartlinks/success","cancel_url":"https://northstar-distribution.co.uk/addons/release-smartlinks/cancel"}}}}}},"/api/v1/addons/checkout/{checkout_id}/status":{"get":{"tags":["Add-Ons"],"summary":"View Add-On Checkout Status","operationId":"getAddonCheckoutStatus","description":"Check an add-on checkout by checkout_id. Use this after the user returns from payment or after an embedded payment component reports completion.","parameters":[{"name":"checkout_id","in":"path","required":true,"description":"Public checkout reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"39b189c1-8f8e-4df2-8632-176f87f791a1"}],"responses":{"200":{"description":"View Add-On Checkout Status succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"addon_slug":{"type":"string","example":"release-smartlinks","description":"Public slug for the add-on, used in add-on checkout and lifecycle endpoint paths."},"addon_version":{"type":"string","example":"1.3.0","description":"Version of the add-on being purchased or activated, matching a version available to the organization."},"status":{"type":"string","example":"succeeded","description":"Current lifecycle status for this record."},"installed":{"type":"boolean","example":true,"description":"Whether the add-on is currently installed for the organization."},"license_id":{"type":"string","example":"f05e3ae3-4b17-45bd-a22f-e33d715b3486","format":"uuid","description":"Stable public license reference. Use this value in related endpoint paths and request bodies."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","addon_slug":"release-smartlinks","addon_version":"1.3.0","status":"succeeded","installed":true,"license_id":"f05e3ae3-4b17-45bd-a22f-e33d715b3486"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/artists":{"get":{"tags":["Artists"],"summary":"List Artists","operationId":"listArtists","description":"List Artists. Use it to create and maintain artist profiles that can be attached to releases, tracks, primary artist credits, featured artist credits, and catalog searches. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"search","in":"query","required":false,"description":"Search term for matching visible records.","schema":{"type":"string","example":"midnight"},"example":"midnight"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20},{"name":"sort","in":"query","required":false,"description":"Sort direction for creation date.","schema":{"type":"string","example":"desc"},"example":"desc"},{"name":"X-User-Id","in":"header","required":false,"description":"Optional user_id to perform an allowed action for a user in the same organization.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"List Artists succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Stable public artist reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this data."},"artist_type":{"type":"string","example":"Primary Artist","description":"Artist classification used for DSP metadata and credit display."},"spotify_id":{"type":"string","example":"3mY7kJqR8B2nQvP6LxT4Za","description":"Optional external Spotify artist reference for matching catalog profiles. It is not a SpaceMedia API path reference; use artist_id for SpaceMedia API calls."},"bio":{"type":"string","example":"Electronic artist and producer from London.","description":"Artist biography or descriptive profile text."},"country":{"type":"string","example":"GB","description":"Country associated with the user, artist, or organization record."},"releases_count":{"type":"integer","example":2,"description":"Number of releases currently associated with the artist."},"tracks_count":{"type":"integer","example":7,"description":"Number of tracks currently associated with the artist."},"total_streams":{"type":"integer","example":125000,"description":"Total reported streams when reporting data is available."},"created_at":{"type":"string","example":"2026-06-01T11:00:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","artist_type":"Primary Artist","spotify_id":"3mY7kJqR8B2nQvP6LxT4Za","bio":"Electronic artist and producer from London.","country":"GB","releases_count":2,"tracks_count":7,"total_streams":125000,"created_at":"2026-06-01T11:00:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for search. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"search":["The search field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Artists"],"summary":"Create Artist","operationId":"createArtist","description":"Create Artist. Use it to create and maintain artist profiles that can be attached to releases, tracks, primary artist credits, featured artist credits, and catalog searches. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"X-User-Id","in":"header","required":true,"description":"Required user_id for catalog ownership and quota context. The client must also have users:act-as.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"Create Artist succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Artist created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Stable public artist reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this data."},"artist_type":{"type":"string","example":"Primary Artist","description":"Artist classification used for DSP metadata and credit display."},"spotify_id":{"type":"string","example":"3mY7kJqR8B2nQvP6LxT4Za","description":"Optional external Spotify artist reference for matching catalog profiles. It is not a SpaceMedia API path reference; use artist_id for SpaceMedia API calls."},"bio":{"type":"string","example":"Electronic artist and producer from London.","description":"Artist biography or descriptive profile text."},"country":{"type":"string","example":"GB","description":"Country associated with the user, artist, or organization record."},"releases_count":{"type":"integer","example":2,"description":"Number of releases currently associated with the artist."},"tracks_count":{"type":"integer","example":7,"description":"Number of tracks currently associated with the artist."},"total_streams":{"type":"integer","example":125000,"description":"Total reported streams when reporting data is available."},"created_at":{"type":"string","example":"2026-06-01T11:00:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Artist created.","data":{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","artist_type":"Primary Artist","spotify_id":"3mY7kJqR8B2nQvP6LxT4Za","bio":"Electronic artist and producer from London.","country":"GB","releases_count":2,"tracks_count":7,"total_streams":125000,"created_at":"2026-06-01T11:00:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"name":["The name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Nova Vale","description":"Display name for this request body."},"bio":{"type":"string","example":"Electronic artist and producer from London.","description":"Artist biography or descriptive profile text."},"spotify_id":{"type":"string","example":"3mY7kJqR8B2nQvP6LxT4Za","description":"Optional external Spotify artist reference for matching catalog profiles. It is not a SpaceMedia API path reference; use artist_id for SpaceMedia API calls."},"country":{"type":"string","example":"GB","description":"Country associated with the user, artist, or organization record."}},"required":["name"]},"example":{"name":"Nova Vale","bio":"Electronic artist and producer from London.","spotify_id":"3mY7kJqR8B2nQvP6LxT4Za","country":"GB"}}}}}},"/api/v1/artists/{artist_id}":{"post":{"tags":["Artists"],"summary":"Update Artist","operationId":"updateArtist","description":"Update Artist. Use it to create and maintain artist profiles that can be attached to releases, tracks, primary artist credits, featured artist credits, and catalog searches. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"artist_id","in":"path","required":true,"description":"Public artist reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802"},{"name":"X-User-Id","in":"header","required":true,"description":"Required user_id for catalog ownership and quota context. The client must also have users:act-as.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"Update Artist succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Artist updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Stable public artist reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this data."},"artist_type":{"type":"string","example":"Primary Artist","description":"Artist classification used for DSP metadata and credit display."},"spotify_id":{"type":"string","example":"3mY7kJqR8B2nQvP6LxT4Za","description":"Optional external Spotify artist reference for matching catalog profiles. It is not a SpaceMedia API path reference; use artist_id for SpaceMedia API calls."},"bio":{"type":"string","example":"Electronic artist, vocalist, and producer from London.","description":"Artist biography or descriptive profile text."},"country":{"type":"string","example":"GB","description":"Country associated with the user, artist, or organization record."},"releases_count":{"type":"integer","example":2,"description":"Number of releases currently associated with the artist."},"tracks_count":{"type":"integer","example":7,"description":"Number of tracks currently associated with the artist."},"total_streams":{"type":"integer","example":125000,"description":"Total reported streams when reporting data is available."},"created_at":{"type":"string","example":"2026-06-01T11:00:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Artist updated.","data":{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","artist_type":"Primary Artist","spotify_id":"3mY7kJqR8B2nQvP6LxT4Za","bio":"Electronic artist, vocalist, and producer from London.","country":"GB","releases_count":2,"tracks_count":7,"total_streams":125000,"created_at":"2026-06-01T11:00:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"name":["The name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Nova Vale","description":"Display name for this request body."},"bio":{"type":"string","example":"Electronic artist, vocalist, and producer from London.","description":"Artist biography or descriptive profile text."},"spotify_id":{"type":"string","example":"3mY7kJqR8B2nQvP6LxT4Za","description":"Optional external Spotify artist reference for matching catalog profiles. It is not a SpaceMedia API path reference; use artist_id for SpaceMedia API calls."}},"required":["name"]},"example":{"name":"Nova Vale","bio":"Electronic artist, vocalist, and producer from London.","spotify_id":"3mY7kJqR8B2nQvP6LxT4Za"}}}}},"delete":{"tags":["Artists"],"summary":"Delete Artist","operationId":"deleteArtist","description":"Delete Artist. Use it to create and maintain artist profiles that can be attached to releases, tracks, primary artist credits, featured artist credits, and catalog searches. It removes, revokes, or cancels the target when permissions and resource state allow it, then returns a confirmation or policy error.","parameters":[{"name":"artist_id","in":"path","required":true,"description":"Public artist reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802"}],"responses":{"200":{"description":"Delete Artist succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Artist deleted successfully.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Artist deleted successfully."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/invoices/{checkout_id}/pdf":{"get":{"tags":["Billing and Checkouts"],"summary":"Download Billing Invoice PDF","operationId":"downloadBillingInvoicePdf","description":"Download the invoice PDF associated with a checkout_id from billing history. Use the checkout_id returned by checkout or billing history responses, not a numeric transaction reference.","parameters":[{"name":"checkout_id","in":"path","required":true,"description":"Checkout reference from billing history.","schema":{"type":"string","format":"uuid"},"example":"39b189c1-8f8e-4df2-8632-176f87f791a1"}],"responses":{"200":{"description":"Returns the invoice PDF file for the requested public checkout reference.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}},"headers":{"Content-Type":{"description":"PDF media type returned for invoice downloads.","schema":{"type":"string","example":"application/pdf"}},"Content-Disposition":{"description":"Attachment disposition with a generated invoice filename.","schema":{"type":"string","example":"attachment; filename=\"invoice.pdf\""}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in this organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/overview":{"get":{"tags":["Billing and Checkouts"],"summary":"View Billing Overview","operationId":"getBillingOverview","description":"Return organization billing status, saved payment methods, subscription state, history items, and invoice links that the caller is allowed to manage.","parameters":[],"responses":{"200":{"description":"View Billing Overview succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"summary":{"type":"object","additionalProperties":true,"properties":{"active_membership_count":{"type":"integer","example":1,"description":"Number of active membership records visible in this context."},"active_addon_count":{"type":"integer","example":2,"description":"Number of active addon records visible in this context."},"active_subscription_count":{"type":"integer","example":3,"description":"Number of active subscription records visible in this context."},"mrr":{"type":"integer","example":87,"description":"mrr for summary."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."}},"example":{"active_membership_count":1,"active_addon_count":2,"active_subscription_count":3,"mrr":87,"currency":"GBP"},"description":"Short summary value for this object or workflow."},"payment_methods":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"payment_method_id":{"type":"string","example":"payment_method_docs_invalid","description":"Opaque saved payment method reference returned by billing overview. Do not parse provider details from this value."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"brand":{"type":"string","example":"visa","description":"Card brand or payment method brand shown for recognition."},"last4":{"type":"string","example":"4242","description":"Last four digits of a saved card, when available."},"default":{"type":"boolean","example":true,"description":"Whether this value is the default choice for the organization."},"exp_month":{"type":"integer","example":9,"description":"Expiration month for a saved card."},"exp_year":{"type":"integer","example":2028,"description":"Expiration year for a saved card."}},"example":{"payment_method_id":"payment_method_docs_invalid","gateway":"airwallex","brand":"visa","last4":"4242","default":true,"exp_month":9,"exp_year":2028}},"example":[{"payment_method_id":"payment_method_docs_invalid","gateway":"airwallex","brand":"visa","last4":"4242","default":true,"exp_month":9,"exp_year":2028}],"description":"Saved payment methods visible to the organization for billing and checkout recovery."},"payment_recovery":{"type":"object","additionalProperties":true,"properties":{"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"recurring_retry_strategy":{"type":"string","example":"Automated payment recovery for failed recurring payments.","description":"recurring retry strategy for payment_recovery."},"daily":{"type":"string","example":"One retry around 2 hours after failure.","description":"daily for payment_recovery."},"short_cycle":{"type":"string","example":"Retry daily for 2 to 6 day billing cycles.","description":"short cycle for payment_recovery."},"long_cycle":{"type":"string","example":"Retry every 2 days for up to 14 days on weekly, monthly, and yearly cycles.","description":"long cycle for payment_recovery."}},"example":{"gateway":"airwallex","recurring_retry_strategy":"Automated payment recovery for failed recurring payments.","daily":"One retry around 2 hours after failure.","short_cycle":"Retry daily for 2 to 6 day billing cycles.","long_cycle":"Retry every 2 days for up to 14 days on weekly, monthly, and yearly cycles."},"description":"Payment recovery state and actions available for failed or incomplete billing attempts."},"subscriptions":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"subscription_id":{"type":"string","example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","format":"uuid","description":"Stable public subscription reference. Use this value in related endpoint paths and request bodies."},"addon_slug":{"type":"string","example":"release-smartlinks","description":"addon slug for subscriptions."},"addon_name":{"type":"string","example":"Release Smartlinks","description":"addon name for subscriptions."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"amount":{"type":"integer","example":19,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"cycle":{"type":"string","example":"monthly","description":"Billing cycle requested for the add-on checkout, such as monthly or yearly when both are offered."},"next_billing_at":{"type":"string","example":"2026-08-01T09:00:00+00:00","description":"Timestamp for when next billing occurred, formatted as ISO 8601 when available."}},"example":{"subscription_id":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","addon_slug":"release-smartlinks","addon_name":"Release Smartlinks","status":"active","amount":19,"currency":"GBP","cycle":"monthly","next_billing_at":"2026-08-01T09:00:00+00:00"}},"example":[{"subscription_id":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","addon_slug":"release-smartlinks","addon_name":"Release Smartlinks","status":"active","amount":19,"currency":"GBP","cycle":"monthly","next_billing_at":"2026-08-01T09:00:00+00:00"}],"description":"Subscriptions visible to the organization or account."},"history":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"created_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"type":{"type":"string","example":"addon_subscription","description":"Public type or role value for this item."},"label":{"type":"string","example":"Release Smartlinks Monthly","description":"Label name attached to the release metadata."},"customer":{"type":"string","example":"Maya Chen","description":"customer for history."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"success","description":"Current lifecycle status for this record."},"amount":{"type":"integer","example":19,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"invoice_pdf_url":{"type":"string","example":"/api/v1/billing/invoices/39b189c1-8f8e-4df2-8632-176f87f791a1/pdf","description":"Organization-scoped URL for downloading the invoice PDF for this checkout."}},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","created_at":"2026-07-04T10:15:00+00:00","type":"addon_subscription","label":"Release Smartlinks Monthly","customer":"Maya Chen","gateway":"airwallex","status":"success","amount":19,"currency":"GBP","invoice_pdf_url":"/api/v1/billing/invoices/39b189c1-8f8e-4df2-8632-176f87f791a1/pdf"}},"example":[{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","created_at":"2026-07-04T10:15:00+00:00","type":"addon_subscription","label":"Release Smartlinks Monthly","customer":"Maya Chen","gateway":"airwallex","status":"success","amount":19,"currency":"GBP","invoice_pdf_url":"/api/v1/billing/invoices/39b189c1-8f8e-4df2-8632-176f87f791a1/pdf"}],"description":"Billing, checkout, wallet, or activity history entries returned for the workflow."}},"example":{"summary":{"active_membership_count":1,"active_addon_count":2,"active_subscription_count":3,"mrr":87,"currency":"GBP"},"payment_methods":[{"payment_method_id":"payment_method_docs_invalid","gateway":"airwallex","brand":"visa","last4":"4242","default":true,"exp_month":9,"exp_year":2028}],"payment_recovery":{"gateway":"airwallex","recurring_retry_strategy":"Automated payment recovery for failed recurring payments.","daily":"One retry around 2 hours after failure.","short_cycle":"Retry daily for 2 to 6 day billing cycles.","long_cycle":"Retry every 2 days for up to 14 days on weekly, monthly, and yearly cycles."},"subscriptions":[{"subscription_id":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","addon_slug":"release-smartlinks","addon_name":"Release Smartlinks","status":"active","amount":19,"currency":"GBP","cycle":"monthly","next_billing_at":"2026-08-01T09:00:00+00:00"}],"history":[{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","created_at":"2026-07-04T10:15:00+00:00","type":"addon_subscription","label":"Release Smartlinks Monthly","customer":"Maya Chen","gateway":"airwallex","status":"success","amount":19,"currency":"GBP","invoice_pdf_url":"/api/v1/billing/invoices/39b189c1-8f8e-4df2-8632-176f87f791a1/pdf"}]},"description":"Primary response payload for this request."}},"example":{"success":true,"data":{"summary":{"active_membership_count":1,"active_addon_count":2,"active_subscription_count":3,"mrr":87,"currency":"GBP"},"payment_methods":[{"payment_method_id":"payment_method_docs_invalid","gateway":"airwallex","brand":"visa","last4":"4242","default":true,"exp_month":9,"exp_year":2028}],"payment_recovery":{"gateway":"airwallex","recurring_retry_strategy":"Automated payment recovery for failed recurring payments.","daily":"One retry around 2 hours after failure.","short_cycle":"Retry daily for 2 to 6 day billing cycles.","long_cycle":"Retry every 2 days for up to 14 days on weekly, monthly, and yearly cycles."},"subscriptions":[{"subscription_id":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","addon_slug":"release-smartlinks","addon_name":"Release Smartlinks","status":"active","amount":19,"currency":"GBP","cycle":"monthly","next_billing_at":"2026-08-01T09:00:00+00:00"}],"history":[{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","created_at":"2026-07-04T10:15:00+00:00","type":"addon_subscription","label":"Release Smartlinks Monthly","customer":"Maya Chen","gateway":"airwallex","status":"success","amount":19,"currency":"GBP","invoice_pdf_url":"/api/v1/billing/invoices/39b189c1-8f8e-4df2-8632-176f87f791a1/pdf"}]}},"required":["success","data"]},"example":{"success":true,"data":{"summary":{"active_membership_count":1,"active_addon_count":2,"active_subscription_count":3,"mrr":87,"currency":"GBP"},"payment_methods":[{"payment_method_id":"payment_method_docs_invalid","gateway":"airwallex","brand":"visa","last4":"4242","default":true,"exp_month":9,"exp_year":2028}],"payment_recovery":{"gateway":"airwallex","recurring_retry_strategy":"Automated payment recovery for failed recurring payments.","daily":"One retry around 2 hours after failure.","short_cycle":"Retry daily for 2 to 6 day billing cycles.","long_cycle":"Retry every 2 days for up to 14 days on weekly, monthly, and yearly cycles."},"subscriptions":[{"subscription_id":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","addon_slug":"release-smartlinks","addon_name":"Release Smartlinks","status":"active","amount":19,"currency":"GBP","cycle":"monthly","next_billing_at":"2026-08-01T09:00:00+00:00"}],"history":[{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","created_at":"2026-07-04T10:15:00+00:00","type":"addon_subscription","label":"Release Smartlinks Monthly","customer":"Maya Chen","gateway":"airwallex","status":"success","amount":19,"currency":"GBP","invoice_pdf_url":"/api/v1/billing/invoices/39b189c1-8f8e-4df2-8632-176f87f791a1/pdf"}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/activation-trial/cancel":{"post":{"tags":["Billing and Checkouts"],"summary":"Cancel Activation Trial","operationId":"cancelActivationTrial","description":"Cancel the current organization activation trial before its activation charge is attempted. The response returns the updated activation trial state.","parameters":[],"responses":{"200":{"description":"The activation trial was canceled.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Trial canceled. No activation fee will be charged automatically."},"data":{"type":"object","additionalProperties":true,"properties":{"activation_trial":{"type":["object","null"],"additionalProperties":true,"description":"Updated activation trial lifecycle state."}}}}},"example":{"success":true,"message":"Trial canceled. No activation fee will be charged automatically.","data":{"activation_trial":{"status":"canceled","canceled_at":"2026-07-30T15:50:00Z"}}}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The caller cannot manage organization billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The trial cannot be canceled in its current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/payment-methods/{payment_method_id}":{"delete":{"tags":["Billing and Checkouts"],"summary":"Delete Payment Method","operationId":"deletePaymentMethod","description":"Remove a saved payment method by payment_method_id when billing rules allow it. The response confirms removal or explains why the method must remain available.","parameters":[{"name":"payment_method_id","in":"path","required":true,"description":"Opaque saved payment method reference returned by the billing overview. Do not parse provider details from this value.","schema":{"type":"string","example":"payment_method_docs_invalid"},"example":"payment_method_docs_invalid"}],"responses":{"200":{"description":"Delete Payment Method succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Payment method deleted.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Payment method deleted."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/payment-methods/{payment_method_id}/default":{"post":{"tags":["Billing and Checkouts"],"summary":"Set Default Payment Method","operationId":"setDefaultPaymentMethod","description":"Set a saved payment method as the organization default by payment_method_id. Use this after listing billing overview or adding a new payment method.","parameters":[{"name":"payment_method_id","in":"path","required":true,"description":"Opaque saved payment method reference returned by the billing overview. Do not parse provider details from this value.","schema":{"type":"string","example":"payment_method_docs_invalid"},"example":"payment_method_docs_invalid"}],"responses":{"200":{"description":"Set Default Payment Method succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Default payment method updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Default payment method updated."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/payment-methods/{payment_method_id}/manage":{"post":{"tags":["Billing and Checkouts"],"summary":"Create Payment Method Management Session","operationId":"createPaymentMethodManagementSession","description":"Create a hosted payment method management session for a saved payment method by payment_method_id when external management is required. The response returns a redirect_url when available.","parameters":[{"name":"payment_method_id","in":"path","required":true,"description":"Opaque saved payment method reference returned by the billing overview. Do not parse provider details from this value.","schema":{"type":"string","example":"payment_method_docs_invalid"},"example":"payment_method_docs_invalid"}],"responses":{"200":{"description":"Create Payment Method Management Session succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Management flow created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"payment_method_id":{"type":"string","example":"payment_method_docs_invalid","description":"Opaque saved payment method reference returned by billing overview. Do not parse provider details from this value."},"manage_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/payment-methods/manage/docs-payment-method","format":"uri","description":"Public URL returned for this resource or action."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Management flow created.","data":{"payment_method_id":"payment_method_docs_invalid","manage_url":"https://checkout.spacemedia-docs.invalid/payment-methods/manage/docs-payment-method"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/payment-methods/paypal/setup":{"post":{"tags":["Billing and Checkouts"],"summary":"Start PayPal Payment Method Setup","operationId":"startPaypalPaymentMethodSetup","description":"Start a hosted PayPal payment method setup flow for the organization. Redirect the user to redirect_url, then verify with checkout_id after the provider returns.","parameters":[],"responses":{"200":{"description":"Start PayPal Payment Method Setup succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Payment method setup created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"paypal","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Payment method setup created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"paypal","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for success_url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"success_url":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/paypal/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/paypal/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["success_url","cancel_url"]},"example":{"success_url":"https://northstar-distribution.co.uk/billing/paypal/success","cancel_url":"https://northstar-distribution.co.uk/billing/paypal/cancel"}}}}}},"/api/v1/billing/payment-methods/paypal/setup/verify":{"post":{"tags":["Billing and Checkouts"],"summary":"Verify PayPal Payment Method Setup","operationId":"verifyPaypalPaymentMethodSetup","description":"Verify a PayPal payment method setup by checkout_id after the user returns from the provider. The response confirms whether the billing agreement was saved.","parameters":[],"responses":{"200":{"description":"Verify PayPal Payment Method Setup succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Payment method verified.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"payment_method_id":{"type":"string","example":"payment_method_docs_invalid","description":"Opaque saved payment method reference returned by billing overview. Do not parse provider details from this value."},"gateway":{"type":"string","example":"paypal","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"default":{"type":"boolean","example":false,"description":"Whether this value is the default choice for the organization."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Payment method verified.","data":{"payment_method_id":"payment_method_docs_invalid","gateway":"paypal","default":false}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for checkout_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"checkout_id":["The checkout id field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."}},"required":["checkout_id"]},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1"}}}}}},"/api/v1/billing/payment-methods/stripe/setup":{"post":{"tags":["Billing and Checkouts"],"summary":"Start Stripe Payment Method Setup","operationId":"startStripePaymentMethodSetup","description":"Start a hosted Stripe payment method setup flow for the organization. Redirect the user to redirect_url, then verify with checkout_id after the provider returns.","parameters":[],"responses":{"200":{"description":"Start Stripe Payment Method Setup succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Payment method setup created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Payment method setup created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"stripe","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for success_url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"success_url":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/payment-methods/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/payment-methods/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["success_url","cancel_url"]},"example":{"success_url":"https://northstar-distribution.co.uk/billing/payment-methods/success","cancel_url":"https://northstar-distribution.co.uk/billing/payment-methods/cancel"}}}}}},"/api/v1/billing/payment-methods/stripe/setup/intent":{"post":{"tags":["Billing and Checkouts"],"summary":"Create Embedded Payment Method Setup","operationId":"createEmbeddedPaymentMethodSetup","description":"Create an embedded payment method setup session for collecting a payment method inside your interface. Store checkout_id and use embedded_checkout_token only in the payment collection component.","parameters":[],"responses":{"200":{"description":"Create Embedded Payment Method Setup succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Setup intent created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"embedded_checkout_token":{"type":"string","example":"docs_invalid_embedded_checkout_token","description":"Short-lived embedded checkout token. Treat this value as sensitive payment data and never log it or expose it in support tickets.","format":"password","x-sensitive":true}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Setup intent created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"stripe","embedded_checkout_token":"docs_invalid_embedded_checkout_token"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/payment-methods/stripe/setup/intent/verify":{"post":{"tags":["Billing and Checkouts"],"summary":"Verify Embedded Stripe Setup Intent","operationId":"verifyStripeSetupIntent","description":"Verify an embedded Stripe payment method setup by checkout_id after the payment component confirms completion. The response returns the saved payment method state.","parameters":[],"responses":{"200":{"description":"Verify Embedded Stripe Setup Intent succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Payment method verified.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"payment_method_id":{"type":"string","example":"payment_method_docs_invalid","description":"Opaque saved payment method reference returned by billing overview. Do not parse provider details from this value."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"default":{"type":"boolean","example":true,"description":"Whether this value is the default choice for the organization."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Payment method verified.","data":{"payment_method_id":"payment_method_docs_invalid","gateway":"stripe","default":true}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for checkout_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"checkout_id":["The checkout id field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."}},"required":["checkout_id"]},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1"}}}}}},"/api/v1/billing/payment-methods/stripe/setup/verify":{"post":{"tags":["Billing and Checkouts"],"summary":"Verify Stripe Payment Method Setup","operationId":"verifyStripePaymentMethodSetup","description":"Verify a hosted Stripe payment method setup by checkout_id after the user returns from the provider. The response confirms whether the payment method was saved.","parameters":[],"responses":{"200":{"description":"Verify Stripe Payment Method Setup succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Payment method verified.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"payment_method_id":{"type":"string","example":"payment_method_docs_invalid","description":"Opaque saved payment method reference returned by billing overview. Do not parse provider details from this value."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"default":{"type":"boolean","example":true,"description":"Whether this value is the default choice for the organization."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Payment method verified.","data":{"payment_method_id":"payment_method_docs_invalid","gateway":"stripe","default":true}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for checkout_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"checkout_id":["The checkout id field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."}},"required":["checkout_id"]},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1"}}}}}},"/api/v1/billing/subscriptions/{subscription_type}/{subscription_id}/cancel":{"post":{"tags":["Billing and Checkouts"],"summary":"Cancel Billing Subscription","operationId":"cancelBillingSubscription","description":"Cancel an organization billing subscription by subscription_type and subscription_id. The response confirms the cancellation state visible to the caller.","parameters":[{"name":"subscription_type","in":"path","required":true,"description":"Subscription family to update.","schema":{"type":"string","enum":["membership","addon"],"example":"membership"},"example":"membership"},{"name":"subscription_id","in":"path","required":true,"description":"Public subscription reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d"}],"responses":{"200":{"description":"Cancel Billing Subscription succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Subscription cancelled.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Subscription cancelled."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/billing/subscriptions/{subscription_type}/{subscription_id}/resume":{"post":{"tags":["Billing and Checkouts"],"summary":"Resume Billing Subscription","operationId":"resumeBillingSubscription","description":"Resume a canceled or paused organization billing subscription by subscription_type and subscription_id when the plan state allows it.","parameters":[{"name":"subscription_type","in":"path","required":true,"description":"Subscription family to update.","schema":{"type":"string","enum":["membership","addon"],"example":"membership"},"example":"membership"},{"name":"subscription_id","in":"path","required":true,"description":"Public subscription reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d"}],"responses":{"200":{"description":"Resume Billing Subscription succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Subscription resumed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Subscription resumed."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/copyright/releases":{"get":{"tags":["Copyright"],"summary":"List Copyright Releases","operationId":"listCopyrightReleases","description":"List releases with copyright check state visible to the organization. Use release_id values to inspect one release in detail.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List Copyright Releases succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"status":{"type":"string","example":"needs_review","description":"Current lifecycle status for this record."},"checks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"copyright_check_id":{"type":"string","example":"acr_midnight_atlas_20260704","description":"Organization-facing copyright check reference for this release or track."},"detection_service":{"type":"string","example":"audio_fingerprint","description":"Public label for the copyright detection service used for this check."},"status":{"type":"string","example":"needs_review","description":"Current lifecycle status for this record."},"matched_tracks":{"type":"integer","example":1,"description":"matched tracks for checks."}}},"description":"Readiness, copyright, or validation checks returned for the release or workflow."},"documents":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"document_id":{"type":"string","example":"a211d645-b1c8-43f7-8c7e-1b40adc2cc7c","format":"uuid","description":"Stable public document reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"requested","description":"Current lifecycle status for this record."},"reason":{"type":"string","example":"Please upload proof of licensed sample clearance.","description":"Reason attached to the document status or review item."}}},"description":"Supporting documents attached to the release, track, or review workflow."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"status":"needs_review","checks":[{"copyright_check_id":"acr_midnight_atlas_20260704","detection_service":"audio_fingerprint","status":"needs_review","matched_tracks":1}],"documents":[{"document_id":"a211d645-b1c8-43f7-8c7e-1b40adc2cc7c","status":"requested","reason":"Please upload proof of licensed sample clearance."}]}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/copyright/releases/{release_id}":{"get":{"tags":["Copyright"],"summary":"View Copyright Release","operationId":"getCopyrightRelease","description":"Return copyright check details for one release by release_id, including status, document state, and wallet-related context visible to the caller.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"View Copyright Release succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"status":{"type":"string","example":"needs_review","description":"Current lifecycle status for this record."},"checks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"copyright_check_id":{"type":"string","example":"acr_midnight_atlas_20260704","description":"Organization-facing copyright check reference for this release or track."},"detection_service":{"type":"string","example":"audio_fingerprint","description":"Public label for the copyright detection service used for this check."},"status":{"type":"string","example":"needs_review","description":"Current lifecycle status for this record."},"matched_tracks":{"type":"integer","example":1,"description":"matched tracks for checks."}}},"description":"Readiness, copyright, or validation checks returned for the release or workflow."},"documents":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"document_id":{"type":"string","example":"a211d645-b1c8-43f7-8c7e-1b40adc2cc7c","format":"uuid","description":"Stable public document reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"requested","description":"Current lifecycle status for this record."},"reason":{"type":"string","example":"Please upload proof of licensed sample clearance.","description":"Reason attached to the document status or review item."}}},"description":"Supporting documents attached to the release, track, or review workflow."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"status":"needs_review","checks":[{"copyright_check_id":"acr_midnight_atlas_20260704","detection_service":"audio_fingerprint","status":"needs_review","matched_tracks":1}],"documents":[{"document_id":"a211d645-b1c8-43f7-8c7e-1b40adc2cc7c","status":"requested","reason":"Please upload proof of licensed sample clearance."}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/copyright/statistics":{"get":{"tags":["Copyright"],"summary":"View Copyright Statistics","operationId":"getCopyrightStatistics","description":"Return aggregate copyright check statistics for the organization, including recent usage and release-level outcomes where available.","parameters":[],"responses":{"200":{"description":"View Copyright Statistics succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"wallet_id":{"type":"string","example":"1899e9c2-6b45-4d13-aed4-7f070d810905","format":"uuid","description":"Stable public wallet reference. Use this value in related endpoint paths and request bodies."},"balance":{"type":"integer","example":120,"description":"Current credit, wallet, or account balance shown in the response currency or unit."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"releases":{"type":"object","additionalProperties":true,"properties":{"total":{"type":"integer","example":4,"description":"Total number of records matching the current filters."},"clear":{"type":"integer","example":3,"description":"clear for releases."},"needs_review":{"type":"integer","example":1,"description":"needs review for releases."},"blocked":{"type":"integer","example":0,"description":"blocked for releases."}},"description":"Releases visible for the current organization and permission scope."},"documents_requested":{"type":"integer","example":1,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"last_checked_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last checked occurred, formatted as ISO 8601 when available."},"trend":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"date":{"type":"string","example":"2026-07-01","format":"date","description":"date for trend."},"clear":{"type":"integer","example":2,"description":"clear for trend."},"needs_review":{"type":"integer","example":1,"description":"needs review for trend."}}},"description":"Trend values used for reporting, analytics, or wallet usage summaries."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"wallet_id":"1899e9c2-6b45-4d13-aed4-7f070d810905","balance":120,"currency":"GBP","releases":{"total":4,"clear":3,"needs_review":1,"blocked":0},"documents_requested":1,"last_checked_at":"2026-07-04T10:15:00+00:00","trend":[{"date":"2026-07-01","clear":2,"needs_review":1}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/copyright/summary":{"get":{"tags":["Copyright"],"summary":"View Copyright Summary","operationId":"getCopyrightSummary","description":"Return copyright check availability, wallet summary, and release readiness counts for the organization. Use it to decide whether checks can be started or need more credits.","parameters":[],"responses":{"200":{"description":"View Copyright Summary succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"wallet_id":{"type":"string","example":"1899e9c2-6b45-4d13-aed4-7f070d810905","format":"uuid","description":"Stable public wallet reference. Use this value in related endpoint paths and request bodies."},"balance":{"type":"integer","example":120,"description":"Current credit, wallet, or account balance shown in the response currency or unit."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"releases":{"type":"object","additionalProperties":true,"properties":{"total":{"type":"integer","example":4,"description":"Total number of records matching the current filters."},"clear":{"type":"integer","example":3,"description":"clear for releases."},"needs_review":{"type":"integer","example":1,"description":"needs review for releases."},"blocked":{"type":"integer","example":0,"description":"blocked for releases."}},"description":"Releases visible for the current organization and permission scope."},"documents_requested":{"type":"integer","example":1,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"last_checked_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last checked occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"wallet_id":"1899e9c2-6b45-4d13-aed4-7f070d810905","balance":120,"currency":"GBP","releases":{"total":4,"clear":3,"needs_review":1,"blocked":0},"documents_requested":1,"last_checked_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/copyright/wallet":{"get":{"tags":["Copyright"],"summary":"View Copyright Wallet","operationId":"getCopyrightWallet","description":"Return current copyright wallet balance and credit package information visible to the organization. Use this before starting checks or purchasing credits.","parameters":[],"responses":{"200":{"description":"View Copyright Wallet succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"wallet_id":{"type":"string","example":"1899e9c2-6b45-4d13-aed4-7f070d810905","format":"uuid","description":"Stable public wallet reference. Use this value in related endpoint paths and request bodies."},"balance":{"type":"integer","example":120,"description":"Current credit, wallet, or account balance shown in the response currency or unit."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"low_balance":{"type":"boolean","example":false,"description":"Whether the wallet or credit balance is below the recommended threshold."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"wallet_id":"1899e9c2-6b45-4d13-aed4-7f070d810905","balance":120,"currency":"GBP","low_balance":false}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/copyright/wallet/top-up":{"post":{"tags":["Copyright"],"summary":"Create Copyright Wallet Top-Up","operationId":"createCopyrightWalletTopUp","description":"Create a checkout to add credits to the copyright wallet. Store checkout_id and verify the top-up before assuming new credits are available.","parameters":[],"responses":{"200":{"description":"Create Copyright Wallet Top-Up succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"top_up_id":{"type":"string","example":"2b8a0b6b-bca0-4b7f-8049-672e9a9d2928","format":"uuid","description":"Stable public top up reference. Use this value in related endpoint paths and request bodies."},"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"quote":{"type":"object","additionalProperties":true,"properties":{"credits":{"type":"integer","example":100,"description":"credits for quote."},"amount":{"type":"integer","example":25,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."}},"description":"Quoted checkout or billing amount before the user confirms payment."},"checkout":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"embedded_checkout_token":{"type":"string","example":"docs_invalid_embedded_checkout_token","description":"Short-lived embedded checkout token. Treat this value as sensitive payment data and never log it or expose it in support tickets.","format":"password","x-sensitive":true},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"description":"Checkout object containing the public checkout reference, gateway, status, and continuation fields."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"top_up_id":"2b8a0b6b-bca0-4b7f-8049-672e9a9d2928","checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","status":"pending","quote":{"credits":100,"amount":25,"currency":"GBP"},"checkout":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"airwallex","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","embedded_checkout_token":"docs_invalid_embedded_checkout_token","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for currency. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"currency":["The currency field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"package_code":{"type":"string","example":"copyright_100","description":"PACKAGE CODE code used for catalog, country, currency, or rights metadata."},"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/copyright/top-up/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/copyright/top-up/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["currency","package_code","success_url","cancel_url"]},"example":{"currency":"GBP","package_code":"copyright_100","success_url":"https://northstar-distribution.co.uk/copyright/top-up/success","cancel_url":"https://northstar-distribution.co.uk/copyright/top-up/cancel"}}}}}},"/api/v1/copyright/wallet/top-up/{checkout_id}/status":{"get":{"tags":["Copyright"],"summary":"Check Copyright Wallet Top-Up Status","operationId":"getCopyrightTopUpStatus","description":"Check a copyright wallet top-up by checkout_id. Use it after payment completion to confirm whether wallet credits were applied.","parameters":[{"name":"checkout_id","in":"path","required":true,"description":"Checkout reference returned when the wallet top-up was created.","schema":{"type":"string","format":"uuid"},"example":"39b189c1-8f8e-4df2-8632-176f87f791a1"}],"responses":{"200":{"description":"Check Copyright Wallet Top-Up Status succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"top_up_id":{"type":"string","example":"2b8a0b6b-bca0-4b7f-8049-672e9a9d2928","format":"uuid","description":"Stable public top up reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"succeeded","description":"Current lifecycle status for this record."},"credits":{"type":"integer","example":100,"description":"Number of wallet or account credits available, used, or being purchased."},"completed_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when completed occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"top_up_id":"2b8a0b6b-bca0-4b7f-8049-672e9a9d2928","status":"succeeded","credits":100,"completed_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/copyright/wallet/top-ups":{"get":{"tags":["Copyright"],"summary":"List Copyright Top-Ups","operationId":"listCopyrightTopUps","description":"List copyright wallet top-up attempts visible to the caller. Use checkout_id values to verify or inspect specific top-up payment states.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List Copyright Top-Ups succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"top_up_id":{"type":"string","example":"2b8a0b6b-bca0-4b7f-8049-672e9a9d2928","format":"uuid","description":"Stable public top up reference. Use this value in related endpoint paths and request bodies."},"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"quote":{"type":"object","additionalProperties":true,"properties":{"credits":{"type":"integer","example":100,"description":"credits for quote."},"amount":{"type":"integer","example":25,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."}},"description":"Quoted checkout or billing amount before the user confirms payment."},"checkout":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"embedded_checkout_token":{"type":"string","example":"docs_invalid_embedded_checkout_token","description":"Short-lived embedded checkout token. Treat this value as sensitive payment data and never log it or expose it in support tickets.","format":"password","x-sensitive":true},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"description":"Checkout object containing the public checkout reference, gateway, status, and continuation fields."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"top_up_id":"2b8a0b6b-bca0-4b7f-8049-672e9a9d2928","checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","status":"pending","quote":{"credits":100,"amount":25,"currency":"GBP"},"checkout":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"airwallex","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","embedded_checkout_token":"docs_invalid_embedded_checkout_token","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/copyright/wallet/transactions":{"get":{"tags":["Copyright"],"summary":"List Copyright Wallet Transactions","operationId":"listCopyrightWalletTransactions","description":"List wallet credit movements for copyright checks, including top-ups and usage. Use this to reconcile credit balance changes with release checks.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List Copyright Wallet Transactions succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"wallet_transaction_id":{"type":"string","example":"e6e8f7ed-bda5-4c5f-a461-3cbac9794516","format":"uuid","description":"Stable public wallet transaction reference. Use this value in related endpoint paths and request bodies."},"type":{"type":"string","example":"top_up","description":"Public type or role value for this item."},"credits":{"type":"integer","example":100,"description":"Number of wallet or account credits available, used, or being purchased."},"amount":{"type":"integer","example":25,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"status":{"type":"string","example":"completed","description":"Current lifecycle status for this record."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"wallet_transaction_id":"e6e8f7ed-bda5-4c5f-a461-3cbac9794516","type":"top_up","credits":100,"amount":25,"currency":"GBP","status":"completed","created_at":"2026-07-04T09:30:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/countries":{"get":{"tags":["Reference Data"],"summary":"List Countries","operationId":"listCountries","description":"List Countries. Use it to fetch stable country, territory, language, and catalog option values before building release, rights, billing, or profile forms. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"List Countries succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","example":"GB","description":"Stable public code for a country, territory, permission, package, or status option."},"name":{"type":"string","example":"United Kingdom","description":"Display name for this data."},"phone_code":{"type":"string","example":"+44","description":"PHONE CODE code used for catalog, country, currency, or rights metadata."}}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":[{"code":"GB","name":"United Kingdom","phone_code":"+44"},{"code":"US","name":"United States","phone_code":"+1"}]}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/email-theme/draft":{"post":{"tags":["Email Theme"],"summary":"Save Email Theme Draft","operationId":"saveEmailThemeDraft","description":"Save Email Theme Draft. Use it to save, preview, and publish branded transactional email settings for the organization. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Save Email Theme Draft succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Email theme draft saved.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"sender_name":{"type":"string","example":"Northstar Distribution","description":"Display name shown as the sender on branded transactional email previews and published email settings."},"sender_email":{"type":"string","example":"support@northstar-distribution.co.uk","description":"Reply-capable sender email address used for branded transactional email previews and published email settings."},"primary_color":{"type":"string","example":"#111827","description":"Primary brand color as a hex value used for prominent buttons, links, and branded surfaces."},"footer_text":{"type":"string","example":"Northstar Distribution, London","description":"Short footer text shown in branded transactional emails, usually support or legal copy for the organization."},"mode":{"type":"string","example":"draft","description":"Mode used by the workflow, such as hosted checkout, embedded checkout, draft, preview, or published state."},"last_published_at":{"type":"string","example":"2026-06-28T16:10:00+00:00","format":"date-time","description":"Timestamp for when last published occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Email theme draft saved.","data":{"sender_name":"Northstar Distribution","sender_email":"support@northstar-distribution.co.uk","primary_color":"#111827","footer_text":"Northstar Distribution, London","mode":"draft","last_published_at":"2026-06-28T16:10:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for sender_name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"sender_name":["The sender name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"sender_name":{"type":"string","example":"Northstar Distribution","description":"Display name shown as the sender on branded transactional email previews and published email settings."},"sender_email":{"type":"string","example":"support@northstar-distribution.co.uk","description":"Reply-capable sender email address used for branded transactional email previews and published email settings."},"primary_color":{"type":"string","example":"#111827","description":"Primary brand color as a hex value used for prominent buttons, links, and branded surfaces."},"footer_text":{"type":"string","example":"Northstar Distribution, London","description":"Short footer text shown in branded transactional emails, usually support or legal copy for the organization."}},"required":["sender_name","sender_email","primary_color"]},"example":{"sender_name":"Northstar Distribution","sender_email":"support@northstar-distribution.co.uk","primary_color":"#111827","footer_text":"Northstar Distribution, London"}}}}}},"/api/v1/email-theme/preview":{"post":{"tags":["Email Theme"],"summary":"Preview Email Theme","operationId":"previewEmailTheme","description":"Preview Email Theme. Use it to save, preview, and publish branded transactional email settings for the organization. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Preview Email Theme succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"preview_html":{"type":"string","example":"<html><body><h1>Midnight Atlas submitted</h1></body></html>","description":"Rendered email preview HTML for the requested template and draft settings."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"preview_html":"<html><body><h1>Midnight Atlas submitted</h1></body></html>"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for template. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"template":["The template field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"template":{"type":"string","example":"release_submitted","description":"Email template key to preview, such as an invitation, release notification, or billing message supported by the account."},"recipient_email":{"type":"string","example":"ops@northstar-distribution.co.uk","description":"Email address that should receive the preview message."}},"required":["template","recipient_email"]},"example":{"template":"release_submitted","recipient_email":"ops@northstar-distribution.co.uk"}}}}}},"/api/v1/email-theme/profile":{"get":{"tags":["Email Theme"],"summary":"View Email Theme Profile","operationId":"getEmailThemeProfile","description":"View Email Theme Profile. Use it to save, preview, and publish branded transactional email settings for the organization. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"View Email Theme Profile succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"sender_name":{"type":"string","example":"Northstar Distribution","description":"Display name shown as the sender on branded transactional email previews and published email settings."},"sender_email":{"type":"string","example":"support@northstar-distribution.co.uk","description":"Reply-capable sender email address used for branded transactional email previews and published email settings."},"primary_color":{"type":"string","example":"#111827","description":"Primary brand color as a hex value used for prominent buttons, links, and branded surfaces."},"footer_text":{"type":"string","example":"Northstar Distribution, London","description":"Short footer text shown in branded transactional emails, usually support or legal copy for the organization."},"mode":{"type":"string","example":"draft","description":"Mode used by the workflow, such as hosted checkout, embedded checkout, draft, preview, or published state."},"last_published_at":{"type":"string","example":"2026-06-28T16:10:00+00:00","format":"date-time","description":"Timestamp for when last published occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"sender_name":"Northstar Distribution","sender_email":"support@northstar-distribution.co.uk","primary_color":"#111827","footer_text":"Northstar Distribution, London","mode":"draft","last_published_at":"2026-06-28T16:10:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/email-theme/publish":{"post":{"tags":["Email Theme"],"summary":"Publish Email Theme","operationId":"publishEmailTheme","description":"Publish Email Theme. Use it to save, preview, and publish branded transactional email settings for the organization. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Publish Email Theme succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Email theme published.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"sender_name":{"type":"string","example":"Northstar Distribution","description":"Display name shown as the sender on branded transactional email previews and published email settings."},"sender_email":{"type":"string","example":"support@northstar-distribution.co.uk","description":"Reply-capable sender email address used for branded transactional email previews and published email settings."},"primary_color":{"type":"string","example":"#111827","description":"Primary brand color as a hex value used for prominent buttons, links, and branded surfaces."},"footer_text":{"type":"string","example":"Northstar Distribution, London","description":"Short footer text shown in branded transactional emails, usually support or legal copy for the organization."},"mode":{"type":"string","example":"published","description":"Mode used by the workflow, such as hosted checkout, embedded checkout, draft, preview, or published state."},"last_published_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last published occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Email theme published.","data":{"sender_name":"Northstar Distribution","sender_email":"support@northstar-distribution.co.uk","primary_color":"#111827","footer_text":"Northstar Distribution, London","mode":"published","last_published_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/labels":{"get":{"tags":["Account Settings"],"summary":"List Labels","operationId":"listLabels","description":"List Labels. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"search","in":"query","required":false,"description":"Search term for matching visible records.","schema":{"type":"string","example":"midnight"},"example":"midnight"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20},{"name":"sort","in":"query","required":false,"description":"Sort direction for creation date.","schema":{"type":"string","example":"desc"},"example":"desc"}],"responses":{"200":{"description":"List Labels succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"label_id":{"type":"string","example":"7da47646-3011-43f8-b497-8a5b1bc2d546","format":"uuid","description":"Stable public label reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Night Shift Records","description":"Display name for this data."},"releases_count":{"type":"integer","example":18,"description":"Number of releases currently associated with the artist."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"label_id":"7da47646-3011-43f8-b497-8a5b1bc2d546","name":"Night Shift Records","releases_count":18,"created_at":"2026-07-04T09:30:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for search. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"search":["The search field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Account Settings"],"summary":"Create Label","operationId":"createLabel","description":"Create Label. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Create Label succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Label created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"label_id":{"type":"string","example":"45ac6d34-9374-4fa6-a6fc-08bd49183a12","format":"uuid","description":"Stable public label reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Aurora Tape Club","description":"Display name for this data."},"releases_count":{"type":"integer","example":18,"description":"Number of releases currently associated with the artist."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Label created.","data":{"label_id":"45ac6d34-9374-4fa6-a6fc-08bd49183a12","name":"Aurora Tape Club","releases_count":18,"created_at":"2026-07-04T09:30:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"name":["The name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Aurora Tape Club","description":"Display name for this request body."}},"required":["name"]},"example":{"name":"Aurora Tape Club"}}}}}},"/api/v1/labels/{label_id}":{"get":{"tags":["Account Settings"],"summary":"View Label","operationId":"getLabel","description":"View Label. Use it to manage the authenticated user profile, account labels, active sessions, and notification preferences that are visible inside the organization account. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"label_id","in":"path","required":true,"description":"Public label reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7da47646-3011-43f8-b497-8a5b1bc2d546"}],"responses":{"200":{"description":"View Label succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"label_id":{"type":"string","example":"7da47646-3011-43f8-b497-8a5b1bc2d546","format":"uuid","description":"Stable public label reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Night Shift Records","description":"Display name for this data."},"releases_count":{"type":"integer","example":18,"description":"Number of releases currently associated with the artist."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"label_id":"7da47646-3011-43f8-b497-8a5b1bc2d546","name":"Night Shift Records","releases_count":18,"created_at":"2026-07-04T09:30:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/me":{"get":{"tags":["Authentication"],"summary":"Get Authenticated API Context","operationId":"getAuthenticatedApiContext","description":"Validate the bearer token currently being used by the integration. The response confirms expiry, API client name, and organization name without returning storage identifiers or secret material.","parameters":[],"responses":{"200":{"description":"Token is valid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"expires_at":{"type":"string","format":"date-time","example":"2026-07-04T11:30:00+00:00","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."},"client":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Northstar Distribution API","description":"Display name for this client."},"organization_name":{"type":"string","example":"Northstar Distribution","description":"Display name of the organization that owns the record."},"capabilities":{"type":"array","items":{"type":"string"},"example":["catalog:read"],"description":"Effective domain capabilities granted to this API client."}},"example":{"name":"Northstar Distribution API","organization_name":"Northstar Distribution","capabilities":["catalog:read"]},"description":"API client context associated with the bearer token."},"organization":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Northstar Distribution","description":"Display name for this organization."}},"example":{"name":"Northstar Distribution"},"description":"Organization summary scoped to the authenticated API credential."}},"example":{"expires_at":"2026-07-04T11:30:00+00:00","client":{"name":"Northstar Distribution API","organization_name":"Northstar Distribution","capabilities":["catalog:read"]},"organization":{"name":"Northstar Distribution"}},"description":"Primary response payload for this request."}},"example":{"success":true,"data":{"expires_at":"2026-07-04T11:30:00+00:00","client":{"name":"Northstar Distribution API","organization_name":"Northstar Distribution"},"organization":{"name":"Northstar Distribution"}}},"required":["success","data"]},"example":{"success":true,"data":{"expires_at":"2026-07-04T11:30:00+00:00","client":{"name":"Northstar Distribution API","organization_name":"Northstar Distribution"},"organization":{"name":"Northstar Distribution"}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/member-invitations":{"get":{"tags":["Members"],"summary":"List Member Invitations","operationId":"listMemberInvitations","description":"List Member Invitations. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List Member Invitations succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"invitation_id":{"type":"string","example":"9406c9cf-4880-43e6-a6db-59cc8c71502f","format":"uuid","description":"Stable public invitation reference. Use this value in related endpoint paths and request bodies."},"email":{"type":"string","example":"catalog.ops@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"role":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this role."}},"description":"Role assigned to the user or member, including its public role reference and display name when expanded."},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"sent_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when sent occurred, formatted as ISO 8601 when available."},"expires_at":{"type":"string","example":"2026-07-11T09:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"invitation_id":"9406c9cf-4880-43e6-a6db-59cc8c71502f","email":"catalog.ops@northstar-distribution.co.uk","role":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"},"status":"pending","sent_at":"2026-07-04T09:30:00+00:00","expires_at":"2026-07-11T09:30:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/member-invitations/{invitation_id}":{"delete":{"tags":["Members"],"summary":"Cancel Member Invitation","operationId":"cancelMemberInvitation","description":"Cancel Member Invitation. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It removes, revokes, or cancels the target when permissions and resource state allow it, then returns a confirmation or policy error.","parameters":[{"name":"invitation_id","in":"path","required":true,"description":"Public invitation reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"9406c9cf-4880-43e6-a6db-59cc8c71502f"}],"responses":{"200":{"description":"Cancel Member Invitation succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Invitation cancelled.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Invitation cancelled."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/member-invitations/{invitation_id}/resend":{"post":{"tags":["Members"],"summary":"Resend Member Invitation","operationId":"resendMemberInvitation","description":"Resend Member Invitation. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"invitation_id","in":"path","required":true,"description":"Public invitation reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"9406c9cf-4880-43e6-a6db-59cc8c71502f"}],"responses":{"200":{"description":"Resend Member Invitation succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Invitation resent.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"invitation_id":{"type":"string","example":"9406c9cf-4880-43e6-a6db-59cc8c71502f","format":"uuid","description":"Stable public invitation reference. Use this value in related endpoint paths and request bodies."},"email":{"type":"string","example":"catalog.ops@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"role":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this role."}},"description":"Role assigned to the user or member, including its public role reference and display name when expanded."},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"sent_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when sent occurred, formatted as ISO 8601 when available."},"expires_at":{"type":"string","example":"2026-07-11T09:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Invitation resent.","data":{"invitation_id":"9406c9cf-4880-43e6-a6db-59cc8c71502f","email":"catalog.ops@northstar-distribution.co.uk","role":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"},"status":"pending","sent_at":"2026-07-04T09:30:00+00:00","expires_at":"2026-07-11T09:30:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/member-permissions":{"get":{"tags":["Members"],"summary":"List Member Permissions","operationId":"listMemberPermissions","description":"List permission keys available for member roles in the organization. Use these keys when creating or updating role permissions.","parameters":[],"responses":{"200":{"description":"List Member Permissions succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"group":{"type":"string","example":"Catalog","description":"group for groups."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."}}},"description":"Permission groups available when configuring member roles."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"groups":[{"group":"Catalog","permissions":["view releases","create releases","update releases","view artists"]},{"group":"Billing","permissions":["view billing","manage subscriptions"]}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/member-roles":{"get":{"tags":["Members"],"summary":"List Member Roles","operationId":"listMemberRoles","description":"List Member Roles. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"List Member Roles succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this roles."},"preset":{"type":"string","example":"catalog_manager","description":"Optional role template used to seed permissions before custom role edits are applied."},"protected":{"type":"boolean","example":false,"description":"protected for roles."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."}}},"description":"Roles assigned to the user or member within the organization."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"roles":[{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager","preset":"catalog_manager","protected":false,"permissions":["view releases","create releases","update releases","view artists","create artists"]}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Members"],"summary":"Create Member Role","operationId":"createMemberRole","description":"Create a custom member role from a name and optional preset. Use the returned role_id when inviting or updating members.","parameters":[],"responses":{"201":{"description":"Create Member Role created the resource and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Role created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"0c6f8128-7795-4974-88ae-9873d3b57df7","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Release Coordinator","description":"Display name for this data."},"preset":{"type":"string","example":"catalog_manager","description":"Optional role template used to seed permissions before custom role edits are applied."},"protected":{"type":"boolean","example":false,"description":"Whether the role or setting is protected from organization-level edits."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Role created.","data":{"role_id":"0c6f8128-7795-4974-88ae-9873d3b57df7","name":"Release Coordinator","preset":"catalog_manager","protected":false,"permissions":["view releases","create releases","update releases","view artists","create artists"]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"name":["The name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Release Coordinator","description":"Display name for this request body."},"preset":{"type":"string","example":"release_manager","description":"Optional role template used to seed permissions before custom role edits are applied."}},"required":["name"]},"example":{"name":"Release Coordinator","preset":"release_manager"}}}}}},"/api/v1/member-roles/{role_id}":{"patch":{"tags":["Members"],"summary":"Update Member Role","operationId":"updateMemberRole","description":"Update Member Role. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It updates only the submitted fields for the target resource and returns the new state using public reference fields.","parameters":[{"name":"role_id","in":"path","required":true,"description":"Public role reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e"}],"responses":{"200":{"description":"Update Member Role succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Role updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Senior Catalog Manager","description":"Display name for this data."},"preset":{"type":"string","example":"catalog_manager","description":"Optional role template used to seed permissions before custom role edits are applied."},"protected":{"type":"boolean","example":false,"description":"Whether the role or setting is protected from organization-level edits."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Role updated.","data":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Senior Catalog Manager","preset":"catalog_manager","protected":false,"permissions":["view releases","create releases","update releases","view artists","create artists"]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"name":["The name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Senior Catalog Manager","description":"Display name for this request body."}},"required":["name"]},"example":{"name":"Senior Catalog Manager"}}}}}},"/api/v1/member-roles/{role_id}/permissions":{"post":{"tags":["Members"],"summary":"Update Member Role Permissions","operationId":"updateMemberRolePermissions","description":"Replace the permission keys assigned to a member role by role_id. Use the member permissions endpoint to discover valid permission keys first.","parameters":[{"name":"role_id","in":"path","required":true,"description":"Public role reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e"}],"responses":{"200":{"description":"Update Member Role Permissions succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Role permissions updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this data."},"preset":{"type":"string","example":"catalog_manager","description":"Optional role template used to seed permissions before custom role edits are applied."},"protected":{"type":"boolean","example":false,"description":"Whether the role or setting is protected from organization-level edits."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Role permissions updated.","data":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager","preset":"catalog_manager","protected":false,"permissions":["view releases","create releases","update releases","view artists","create artists"]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for permissions. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"permissions":["The permissions field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."}},"required":["permissions"]},"example":{"permissions":["view releases","create releases","update releases","view artists"]}}}}}},"/api/v1/members":{"get":{"tags":["Members"],"summary":"List Members","operationId":"listMembers","description":"List Members. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"search","in":"query","required":false,"description":"Search term for matching visible records.","schema":{"type":"string","example":"midnight"},"example":"midnight"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20},{"name":"sort","in":"query","required":false,"description":"Sort direction for creation date.","schema":{"type":"string","example":"desc"},"example":"desc"}],"responses":{"200":{"description":"List Members succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"member_id":{"type":"string","example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","format":"uuid","description":"Stable public member reference for member-management endpoints. Store and use member_id when reading, updating, suspending, unsuspending, or removing a team member."},"first_name":{"type":"string","example":"Eli","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Brooks","description":"Family name for the user or member profile."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this data."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"role":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this role."}},"description":"Role assigned to the user or member, including its public role reference and display name when expanded."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"invited_at":{"type":"string","example":"2026-07-01T12:00:00+00:00","format":"date-time","description":"Timestamp for when invited occurred, formatted as ISO 8601 when available."},"accepted_at":{"type":"string","example":"2026-07-02T09:05:00+00:00","format":"date-time","description":"Timestamp for when accepted occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"member_id":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","first_name":"Eli","last_name":"Brooks","name":"Eli Brooks","email":"eli.brooks@northstar-distribution.co.uk","status":"active","role":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"},"permissions":["view releases","create releases","update releases"],"is_suspended":false,"invited_at":"2026-07-01T12:00:00+00:00","accepted_at":"2026-07-02T09:05:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for search. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"search":["The search field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/members/{member_id}":{"get":{"tags":["Members"],"summary":"Get Member","operationId":"getMember","description":"Get Member. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"member_id","in":"path","required":true,"description":"Public member reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd"}],"responses":{"200":{"description":"Get Member succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"member_id":{"type":"string","example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","format":"uuid","description":"Stable public member reference for member-management endpoints. Store and use member_id when reading, updating, suspending, unsuspending, or removing a team member."},"first_name":{"type":"string","example":"Eli","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Brooks","description":"Family name for the user or member profile."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this data."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"role":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this role."}},"description":"Role assigned to the user or member, including its public role reference and display name when expanded."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"invited_at":{"type":"string","example":"2026-07-01T12:00:00+00:00","format":"date-time","description":"Timestamp for when invited occurred, formatted as ISO 8601 when available."},"accepted_at":{"type":"string","example":"2026-07-02T09:05:00+00:00","format":"date-time","description":"Timestamp for when accepted occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"member_id":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","first_name":"Eli","last_name":"Brooks","name":"Eli Brooks","email":"eli.brooks@northstar-distribution.co.uk","status":"active","role":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"},"permissions":["view releases","create releases","update releases"],"is_suspended":false,"invited_at":"2026-07-01T12:00:00+00:00","accepted_at":"2026-07-02T09:05:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"patch":{"tags":["Members"],"summary":"Update Member","operationId":"updateMember","description":"Update a member profile or role by member_id. Use role_id from member roles and avoid changing access state here, because suspend and unsuspend have dedicated endpoints.","parameters":[{"name":"member_id","in":"path","required":true,"description":"Public member reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd"}],"responses":{"200":{"description":"Update Member succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Member updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"member_id":{"type":"string","example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","format":"uuid","description":"Stable public member reference for member-management endpoints. Store and use member_id when reading, updating, suspending, unsuspending, or removing a team member."},"first_name":{"type":"string","example":"Eli","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Brooks","description":"Family name for the user or member profile."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this data."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"role":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this role."}},"description":"Role assigned to the user or member, including its public role reference and display name when expanded."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"invited_at":{"type":"string","example":"2026-07-01T12:00:00+00:00","format":"date-time","description":"Timestamp for when invited occurred, formatted as ISO 8601 when available."},"accepted_at":{"type":"string","example":"2026-07-02T09:05:00+00:00","format":"date-time","description":"Timestamp for when accepted occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Member updated.","data":{"member_id":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","first_name":"Eli","last_name":"Brooks","name":"Eli Brooks","email":"eli.brooks@northstar-distribution.co.uk","status":"active","role":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"},"permissions":["view releases","create releases","update releases"],"is_suspended":false,"invited_at":"2026-07-01T12:00:00+00:00","accepted_at":"2026-07-02T09:05:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for first_name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"first_name":["The first name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"first_name":{"type":"string","example":"Eli","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Brooks","description":"Family name for the user or member profile."},"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Public role reference from the member roles endpoint. Include it only when changing the member role."}},"minProperties":1,"description":"Send at least one profile or role field to update."},"example":{"first_name":"Eli","last_name":"Brooks","role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e"}}}}},"delete":{"tags":["Members"],"summary":"Remove Member","operationId":"removeMember","description":"Remove Member. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It removes, revokes, or cancels the target when permissions and resource state allow it, then returns a confirmation or policy error.","parameters":[{"name":"member_id","in":"path","required":true,"description":"Public member reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd"}],"responses":{"200":{"description":"Remove Member succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Member removed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Member removed."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/members/{member_id}/suspend":{"post":{"tags":["Members"],"summary":"Suspend Member","operationId":"suspendMember","description":"Suspend Member. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"member_id","in":"path","required":true,"description":"Public member reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd"}],"responses":{"200":{"description":"Suspend Member succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Member suspended.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Member suspended."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/members/{member_id}/unsuspend":{"post":{"tags":["Members"],"summary":"Unsuspend Member","operationId":"unsuspendMember","description":"Unsuspend Member. Use it to invite team members, manage roles, suspend access, resend invitations, and inspect the permission catalog for member administration. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"member_id","in":"path","required":true,"description":"Public member reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd"}],"responses":{"200":{"description":"Unsuspend Member succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Member unsuspended.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Member unsuspended."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/members/invite":{"post":{"tags":["Members"],"summary":"Invite Members","operationId":"inviteMembers","description":"Invite one or more team members by email. Assign either a role_id from member roles or a preset key returned by the member permissions endpoint. Invitations are scoped to the authenticated organization.","parameters":[],"responses":{"201":{"description":"Invite Members created the resource and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Member invitations sent.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"members":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"member_id":{"type":"string","example":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","format":"uuid","description":"Stable public member reference for member-management endpoints. Store and use member_id when reading, updating, suspending, unsuspending, or removing a team member."},"first_name":{"type":"string","example":"Eli","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Brooks","description":"Family name for the user or member profile."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this members."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"role":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this role."}},"description":"role for members."},"permissions":{"type":"array","items":{"type":"string","example":"view releases"},"description":"Permission keys granted by this role or member assignment."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"invited_at":{"type":"string","example":"2026-07-01T12:00:00+00:00","format":"date-time","description":"Timestamp for when invited occurred, formatted as ISO 8601 when available."},"accepted_at":{"type":"string","example":"2026-07-02T09:05:00+00:00","format":"date-time","description":"Timestamp for when accepted occurred, formatted as ISO 8601 when available."}}},"description":"Array of member invitations containing recipient details and role references for each invited person."},"invitations":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"invitation_id":{"type":"string","example":"9406c9cf-4880-43e6-a6db-59cc8c71502f","format":"uuid","description":"Stable public invitation reference. Use this value in related endpoint paths and request bodies."},"email":{"type":"string","example":"catalog.ops@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"role":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this role."}},"description":"role for invitations."},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"sent_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when sent occurred, formatted as ISO 8601 when available."},"expires_at":{"type":"string","example":"2026-07-11T09:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}}},"description":"Pending member invitations visible to the organization."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Member invitations sent.","data":{"members":[{"member_id":"54dbefc4-49b2-4b18-9945-0921fd07a9fd","first_name":"Eli","last_name":"Brooks","name":"Eli Brooks","email":"eli.brooks@northstar-distribution.co.uk","status":"active","role":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"},"permissions":["view releases","create releases","update releases"],"is_suspended":false,"invited_at":"2026-07-01T12:00:00+00:00","accepted_at":"2026-07-02T09:05:00+00:00"}],"invitations":[{"invitation_id":"9406c9cf-4880-43e6-a6db-59cc8c71502f","email":"catalog.ops@northstar-distribution.co.uk","role":{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"},"status":"pending","sent_at":"2026-07-04T09:30:00+00:00","expires_at":"2026-07-11T09:30:00+00:00"}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for members. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"members":["The members field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"emails":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","format":"email","example":"eli.brooks@northstar-distribution.co.uk"},"description":"Email addresses to invite into the organization as team members."},"role_id":{"type":"string","format":"uuid","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","description":"Public role reference from the member roles endpoint. Required when preset is not supplied."},"preset":{"type":"string","example":"label_manager","description":"Preset key from the member permissions endpoint. Required when role_id is not supplied."},"expires_in_days":{"type":"integer","minimum":1,"maximum":90,"example":14,"description":"Number of days before the invitation expires."}},"required":["emails"],"oneOf":[{"required":["role_id"]},{"required":["preset"]}]},"example":{"members":[{"first_name":"Eli","last_name":"Brooks","email":"eli.brooks@northstar-distribution.co.uk","role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e"}],"message":"Please join Northstar Distribution to manage catalog operations."}}}}}},"/api/v1/order/{release_id}/checkout/airwallex":{"post":{"tags":["Billing and Checkouts"],"summary":"Create Airwallex Release Checkout","operationId":"createAirwallexReleaseCheckout","description":"Create Airwallex Release Checkout. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Create Airwallex Release Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"embedded_checkout_token":{"type":"string","example":"docs_invalid_embedded_checkout_token","description":"Short-lived embedded checkout token. Treat this value as sensitive payment data and never log it or expose it in support tickets.","format":"password","x-sensitive":true},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"airwallex","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","embedded_checkout_token":"docs_invalid_embedded_checkout_token","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for success_url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"success_url":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["success_url","cancel_url"]},"example":{"success_url":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/success","cancel_url":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/cancel"}}}}}},"/api/v1/order/{release_id}/checkout/paypal":{"post":{"tags":["Billing and Checkouts"],"summary":"Create PayPal Release Checkout","operationId":"createPaypalReleaseCheckout","description":"Create PayPal Release Checkout. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Create PayPal Release Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"paypal","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"example":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"description":"Release summary or nested release object connected to this workflow."}},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"paypal","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}},"description":"Primary response payload for this request."}},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"paypal","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"paypal","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for success_url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"success_url":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["success_url","cancel_url"]},"example":{"success_url":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/success","cancel_url":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/cancel"}}}}}},"/api/v1/order/{release_id}/checkout/stripe":{"post":{"tags":["Billing and Checkouts"],"summary":"Create Stripe Release Checkout","operationId":"createStripeReleaseCheckout","description":"Create Stripe Release Checkout. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Create Stripe Release Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"example":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"description":"Release summary or nested release object connected to this workflow."}},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"stripe","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}},"description":"Primary response payload for this request."}},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"stripe","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"stripe","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for success_url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"success_url":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["success_url","cancel_url"]},"example":{"success_url":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/success","cancel_url":"https://northstar-distribution.co.uk/releases/midnight-atlas/payment/cancel"}}}}}},"/api/v1/order/checkout/verify":{"post":{"tags":["Billing and Checkouts"],"summary":"Verify Release Checkout","operationId":"verifyReleaseCheckout","description":"Verify a release checkout by checkout_id after payment completion. The response updates the related release order and returns a payment status suitable for the next catalog step.","parameters":[],"responses":{"200":{"description":"Verify Release Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Release checkout verified.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"status":{"type":"string","example":"paid","description":"Current lifecycle status for this record."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Release checkout verified.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"status":"paid"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for checkout_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"checkout_id":["The checkout id field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."}},"required":["checkout_id"]},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1"}}}}}},"/api/v1/order/credits/checkout":{"post":{"tags":["Billing and Checkouts"],"summary":"Create Credits Checkout","operationId":"createCreditsCheckout","description":"Create a checkout for organization credits. Store checkout_id, send the user through the returned payment flow, and verify the checkout before increasing available balance.","parameters":[],"responses":{"200":{"description":"Create Credits Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"embedded_checkout_token":{"type":"string","example":"docs_invalid_embedded_checkout_token","description":"Short-lived embedded checkout token. Treat this value as sensitive payment data and never log it or expose it in support tickets.","format":"password","x-sensitive":true},"amount":{"type":"integer","example":50,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"airwallex","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","embedded_checkout_token":"docs_invalid_embedded_checkout_token","amount":50,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for amount. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"amount":["The amount field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"amount":{"type":"integer","example":50,"description":"Monetary amount in the currency shown on the same object."},"payment_method":{"type":"string","example":"airwallex","description":"Payment method selected for the checkout, using a supported public gateway or saved method value."},"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/credits/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/credits/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["amount","payment_method"]},"example":{"amount":50,"payment_method":"airwallex","success_url":"https://northstar-distribution.co.uk/billing/credits/success","cancel_url":"https://northstar-distribution.co.uk/billing/credits/cancel"}}}}}},"/api/v1/order/credits/checkout/verify":{"post":{"tags":["Billing and Checkouts"],"summary":"Verify Credits Checkout","operationId":"verifyCreditsCheckout","description":"Verify a credits checkout by checkout_id after payment completion. The response confirms whether the credit balance update has been applied.","parameters":[],"responses":{"200":{"description":"Verify Credits Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Credits checkout verified.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"credits_added":{"type":"integer","example":50,"description":"Number of credits added after a successful top-up or credit checkout."},"balance":{"type":"integer","example":170,"description":"Current credit, wallet, or account balance shown in the response currency or unit."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Credits checkout verified.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","credits_added":50,"balance":170}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for checkout_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"checkout_id":["The checkout id field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."}},"required":["checkout_id"]},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1"}}}}}},"/api/v1/packages":{"get":{"tags":["Plans and Upgrades"],"summary":"List Membership Plans","operationId":"listMembershipPlans","description":"List Membership Plans. Use it to compare available subscription and pay-per-release plans before starting a checkout or changing the organization billing setup. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"List Membership Plans succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"package_id":{"type":"string","example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","format":"uuid","description":"Stable public package reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Growth Distribution Monthly","description":"Display name for this data."},"type":{"type":"string","example":"membership","description":"Public type or role value for this item."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"price":{"type":"integer","example":49,"description":"Price for the package, plan, add-on, release order, or credit purchase in the response currency."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"royalty_percentage":{"type":"integer","example":85,"description":"Royalty percentage associated with the package or pay-per-release plan."},"artist_profile_limit":{"type":"integer","example":25,"description":"Maximum number of artist profiles included in the package or plan."},"release_limit":{"type":"integer","example":50,"description":"Maximum number of releases included in the package or plan."},"release_limit_cycle":{"type":"string","example":"monthly","description":"Period over which the release limit applies."},"feature_list":{"type":"array","items":{"type":"string","example":"Unlimited team members"},"description":"List of features included in the package, plan, or add-on."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"package_id":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","name":"Growth Distribution Monthly","type":"membership","status":"published","price":49,"currency":"GBP","royalty_percentage":85,"artist_profile_limit":25,"release_limit":50,"release_limit_cycle":"monthly","feature_list":["Unlimited team members","Priority delivery review","Advanced catalog reporting"]}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/packages/pay-per-release":{"get":{"tags":["Plans and Upgrades"],"summary":"List Pay-Per-Release Plans","operationId":"listPayPerReleasePlans","description":"List Pay-Per-Release Plans. Use it to compare available subscription and pay-per-release plans before starting a checkout or changing the organization billing setup. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"List Pay-Per-Release Plans succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"plan_id":{"type":"string","example":"d93dfb89-27ef-4104-a609-4e6dbd272c37","format":"uuid","description":"Stable public plan reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Single Release Credit","description":"Display name for this data."},"release_type":{"type":"string","example":"single","description":"Release type covered by the pay-per-release plan, such as single, EP, or album."},"active":{"type":"boolean","example":true,"description":"Whether the plan, add-on, or configuration is available for use."},"price":{"type":"integer","example":9,"description":"Price for the package, plan, add-on, release order, or credit purchase in the response currency."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"royalty_percentage":{"type":"integer","example":90,"description":"Royalty percentage associated with the package or pay-per-release plan."},"feature_list":{"type":"array","items":{"type":"string","example":"One single release"},"description":"List of features included in the package, plan, or add-on."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"plan_id":"d93dfb89-27ef-4104-a609-4e6dbd272c37","name":"Single Release Credit","release_type":"single","active":true,"price":9,"currency":"GBP","royalty_percentage":90,"feature_list":["One single release","Standard delivery review"]}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/platform-feedback":{"post":{"tags":["Feedback"],"summary":"Submit Platform Feedback","operationId":"submitPlatformFeedback","description":"Submit feedback about an API, catalog, billing, or account workflow. Include the page_url when feedback came from a visible user interface.","parameters":[],"responses":{"201":{"description":"Submit Platform Feedback created the resource and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Feedback submitted.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"feedback_id":{"type":"string","example":"3ad65f11-6982-4f42-86e7-08976cb55114","format":"uuid","description":"Stable public feedback reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"received","description":"Current lifecycle status for this record."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Feedback submitted.","data":{"feedback_id":"3ad65f11-6982-4f42-86e7-08976cb55114","status":"received"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for category. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"category":["The category field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"category":{"type":"string","example":"api_docs","description":"Feedback category that helps route the message, such as catalog, billing, API, account, or support."},"subject":{"type":"string","example":"Need callback example for release submission","description":"Short feedback subject that summarizes the issue or product request."},"message":{"type":"string","example":"Please add a callback guide for release status changes.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"page_url":{"type":"string","example":"https://docs.spacemedia.uk/delivery-api/introduction","format":"uri","description":"Public URL returned for this resource or action."}},"required":["category","subject","message"]},"example":{"category":"api_docs","subject":"Need callback example for release submission","message":"Please add a callback guide for release status changes.","page_url":"https://docs.spacemedia.uk/delivery-api/introduction"}}}}}},"/api/v1/pre-qc/legal-credit-name":{"post":{"tags":["Releases"],"summary":"Validate Legal Credit Name","operationId":"validateLegalCreditName","description":"Validate a legal credit name and country before storing contributor or rights metadata on a release or track. Use it to catch formatting issues before submission.","parameters":[],"responses":{"200":{"description":"Validate Legal Credit Name succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"valid":{"type":"boolean","example":true,"description":"Whether the submitted value passed validation."},"normalized_name":{"type":"string","example":"Night Shift Records Ltd","description":"Normalized legal credit name returned after validation."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"valid":true,"normalized_name":"Night Shift Records Ltd"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"name":["The name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Night Shift Records Ltd","description":"Display name for this request body."},"country":{"type":"string","example":"GB","description":"Country associated with the user, artist, or organization record."}},"required":["name","country"]},"example":{"name":"Night Shift Records Ltd","country":"GB"}}}}}},"/api/v1/qc/releases/all":{"get":{"tags":["Release Review"],"summary":"List Organization Release Reviews","operationId":"listOrganizationReleaseReviews","description":"List release review records visible inside the authenticated organization. Use this organization-scoped queue to build review dashboards, filters, or status monitors for releases the caller is allowed to inspect.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List Organization Release Reviews succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","example":"submitted","description":"Current lifecycle status for this record."},"delivery_status":{"type":"string","example":"pending_review","description":"Current delivery status shown to the organization."},"delivery_simulated":{"type":"boolean","example":false,"description":"True only when staging completed the delivery lifecycle locally without contacting a DSP or delivery partner."},"submitted_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when submitted occurred, formatted as ISO 8601 when available."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"copyright detection enabled for release."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Release summary or nested release object connected to this workflow."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"status":"submitted","delivery_status":"pending_review","submitted_at":"2026-07-04T09:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":1,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/qc/releases/sent":{"get":{"tags":["Release Review"],"summary":"List Sent Review Releases","operationId":"listSentReviewReleases","description":"List releases sent onward after review. Use this queue to monitor delivery progress without exposing provider repair or operational controls.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List Sent Review Releases succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","example":"sent","description":"Current lifecycle status for this record."},"delivery_status":{"type":"string","example":"delivered","description":"Current delivery status shown to the organization."},"delivery_simulated":{"type":"boolean","example":false,"description":"True only when staging completed the delivery lifecycle locally without contacting a DSP or delivery partner."},"submitted_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when submitted occurred, formatted as ISO 8601 when available."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"copyright detection enabled for release."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Release summary or nested release object connected to this workflow."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"status":"sent","delivery_status":"delivered","submitted_at":"2026-07-04T09:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":1,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/qc/releases/submitted":{"get":{"tags":["Release Review"],"summary":"List Submitted Review Releases","operationId":"listSubmittedReviewReleases","description":"List releases that have been submitted for review and are visible to the caller. Use this queue to monitor review readiness and next actions for submitted catalog items.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List Submitted Review Releases succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","example":"submitted","description":"Current lifecycle status for this record."},"delivery_status":{"type":"string","example":"pending_review","description":"Current delivery status shown to the organization."},"delivery_simulated":{"type":"boolean","example":false,"description":"True only when staging completed the delivery lifecycle locally without contacting a DSP or delivery partner."},"submitted_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when submitted occurred, formatted as ISO 8601 when available."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"copyright detection enabled for release."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Release summary or nested release object connected to this workflow."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"status":"submitted","delivery_status":"pending_review","submitted_at":"2026-07-04T09:30:00+00:00","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":1,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/releases":{"get":{"tags":["Releases"],"summary":"List Releases","operationId":"listReleases","description":"List Releases. Use it to draft releases, update metadata, attach artwork and tracks, define rights, choose territories, and prepare releases for review and delivery. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"search","in":"query","required":false,"description":"Search term for matching visible records.","schema":{"type":"string","example":"midnight"},"example":"midnight"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20},{"name":"sort","in":"query","required":false,"description":"Sort direction for creation date.","schema":{"type":"string","example":"desc"},"example":"desc"},{"name":"status","in":"query","required":false,"description":"Filter by release status.","schema":{"type":"string","example":"draft"},"example":"draft"},{"name":"X-User-Id","in":"header","required":false,"description":"Optional user_id to perform an allowed action for a user in the same organization.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"List Releases succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"Whether copyright checking is enabled for the organization or release workflow."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":1,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for search. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"search":["The search field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Releases"],"summary":"Create Release","operationId":"createRelease","description":"Create Release. Use it to draft releases, update metadata, attach artwork and tracks, define rights, choose territories, and prepare releases for review and delivery. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"X-User-Id","in":"header","required":true,"description":"Required user_id for catalog ownership and quota context. The client must also have users:act-as.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"Create Release succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Release created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"Whether copyright checking is enabled for the organization or release workflow."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":0,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Release created.","data":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":0,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for artists.0.artist_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"artists.0.artist_id":["Choose an artist that belongs to this organization."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Multipart request payload.","content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"cover_art":{"type":"string","description":"Binary cover-art image file. Use JPG or PNG artwork that meets store artwork requirements.","format":"binary"},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"copyright_material":{"type":"boolean","example":false,"description":"Whether the submitter has indicated that copyright-sensitive material is present."},"copyright_links":{"type":"array","items":{"type":"string","format":"uri","example":"https://rights.northstar-distribution.co.uk/midnight-atlas-license.pdf","description":"URL to a license, permission document, or rights note for declared copyrighted material."},"description":"Supporting URLs for rights review when copyright material is declared."},"upc":{"type":"string","example":"5054429191012","description":"UPC supplied for the release, or omitted when one should be assigned later."},"reference":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"remix_version":{"type":"string","example":"","description":"Version label such as Original Mix, Radio Edit, or Remix."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"description":{"type":"string","example":"A late-night electronic single built for DSP delivery.","description":"Human-readable description for this record or workflow."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."}},"required":["title","cover_art","format","artists"]},"example":{"title":"Midnight Atlas","cover_art":"midnight-atlas-cover.jpg","label":"Night Shift Records","copyright_material":false,"copyright_links":[],"upc":"5054429191012","reference":"NSD-2026-041","remix_version":"","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"format":"single","description":"A late-night electronic single built for DSP delivery.","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","type":"Primary Artist"}]}}}}}},"/api/v1/releases/{release_id}":{"get":{"tags":["Releases"],"summary":"View Release","operationId":"getRelease","description":"View Release. Use it to draft releases, update metadata, attach artwork and tracks, define rights, choose territories, and prepare releases for review and delivery. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"},{"name":"X-User-Id","in":"header","required":false,"description":"Optional user_id to perform an allowed action for a user in the same organization.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"View Release succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"Whether copyright checking is enabled for the organization or release workflow."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":1,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Releases"],"summary":"Update Release","operationId":"updateRelease","description":"Update Release. Use it to draft releases, update metadata, attach artwork and tracks, define rights, choose territories, and prepare releases for review and delivery. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"},{"name":"X-User-Id","in":"header","required":true,"description":"Required user_id for catalog ownership and quota context. The client must also have users:act-as.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"Update Release succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Release updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"Whether copyright checking is enabled for the organization or release workflow."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."},"description":{"type":"string","example":"Updated delivery-ready metadata for Midnight Atlas.","description":"Human-readable description for this record or workflow."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Release updated.","data":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":1,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00","description":"Updated delivery-ready metadata for Midnight Atlas."}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for genre. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"genre":["Choose a supported genre for this release."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Multipart request payload.","content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"cover_art":{"description":"Binary cover-art image file. Use JPG or PNG artwork that meets store artwork requirements.","type":["string","null"],"format":"binary"},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"copyright_material":{"type":"boolean","example":false,"description":"Whether the submitter has indicated that copyright-sensitive material is present."},"copyright_links":{"type":"array","items":{"type":"string","format":"uri","example":"https://rights.northstar-distribution.co.uk/midnight-atlas-license.pdf","description":"URL to a license, permission document, or rights note for declared copyrighted material."},"description":"Supporting URLs for rights review when copyright material is declared."},"upc":{"type":"string","example":"5054429191012","description":"UPC supplied for the release, or omitted when one should be assigned later."},"reference":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"remix_version":{"type":"string","example":"","description":"Version label such as Original Mix, Radio Edit, or Remix."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"description":{"type":"string","example":"Updated delivery-ready metadata for Midnight Atlas.","description":"Human-readable description for this record or workflow."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."}},"required":["title"]},"example":{"title":"Midnight Atlas","cover_art":null,"label":"Night Shift Records","copyright_material":false,"copyright_links":[],"upc":"5054429191012","reference":"NSD-2026-041","remix_version":"","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"format":"single","description":"Updated delivery-ready metadata for Midnight Atlas.","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","type":"Primary Artist"}]}}}}},"delete":{"tags":["Releases"],"summary":"Delete Release","operationId":"deleteRelease","description":"Delete Release. Use it to draft releases, update metadata, attach artwork and tracks, define rights, choose territories, and prepare releases for review and delivery. It removes, revokes, or cancels the target when permissions and resource state allow it, then returns a confirmation or policy error.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Delete Release succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Release deleted successfully.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Release deleted successfully."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/releases/{release_id}/cover-art":{"post":{"tags":["Releases"],"summary":"Update Release Cover Art","operationId":"updateReleaseCoverArt","description":"Upload replacement cover art for a release by release_id. The image must satisfy release artwork requirements before the release can pass readiness checks.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Update Release Cover Art succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Cover art updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Cover art updated.","data":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for cover_art. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"cover_art":["The cover art field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Multipart request payload.","content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":true,"properties":{"cover_art":{"type":"string","description":"Binary cover-art image file. Use JPG or PNG artwork that meets store artwork requirements.","format":"binary"}},"required":["cover_art"]},"example":{"cover_art":"midnight-atlas-cover.jpg"}}}}}},"/api/v1/releases/{release_id}/distribution":{"post":{"tags":["Releases"],"summary":"Update Release Distribution","operationId":"updateReleaseDistribution","description":"Update delivery channel and territory selections for a release. Use public channel codes and territory codes that match the organization catalog configuration.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Update Release Distribution succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Distribution settings updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Distribution settings updated.","data":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"territories":["GB","US","DE","NL"]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for channels. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"channels":["The channels field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"channels":{"type":"array","items":{"type":"string","example":"spotify"},"description":"Delivery channel codes selected for the release, such as spotify, apple_music, or youtube_music."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."}},"required":["channels"]},"example":{"channels":["spotify","apple_music","youtube_music"],"territories":["GB","US","DE","NL"]}}}}}},"/api/v1/releases/{release_id}/edit-options":{"get":{"tags":["Releases"],"summary":"Get Release Edit Options","operationId":"getReleaseEditOptions","description":"Return the labels, genres, languages, and artist credit types available when editing a release. The options are scoped to the release owner and authenticated organization.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Release edit options were loaded for the release owner and authenticated organization.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"labels":{"type":"array","items":{"type":"string","example":"Night Shift Records"},"description":"Sorted label names available to the release owner, including the organization default label."},"can_use_custom_labels":{"type":"boolean","example":true,"description":"Whether the release editor can select a custom label name from the returned options."},"default_label_name":{"type":"string","example":"Northstar Distribution","description":"Default label name configured for the organization that owns the release."},"genres":{"type":"array","items":{"type":"string","example":"Electronic"},"description":"Supported music genres available for release and track metadata."},"languages":{"type":"array","items":{"type":"string","example":"English"},"description":"Supported language names available for release and track metadata."},"artist_types":{"type":"array","items":{"type":"string","example":"Primary Artist"},"description":"Supported artist credit roles available for release and track contributors."}},"required":["labels","can_use_custom_labels","default_label_name","genres","languages","artist_types"]},"example":{"labels":["Night Shift Records","Northstar Distribution"],"can_use_custom_labels":true,"default_label_name":"Northstar Distribution","genres":["Electronic","Pop"],"languages":["English","German"],"artist_types":["Primary Artist","Featured Artist","Composer"]}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to edit this release."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested release was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/releases/{release_id}/license":{"post":{"tags":["Releases"],"summary":"Update Release License","operationId":"updateReleaseLicense","description":"Update release rights and licensing metadata, including dates, rights holder names, price category, license type, and territory availability.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Update Release License succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Release license updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"Whether copyright checking is enabled for the organization or release workflow."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Release license updated.","data":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":1,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for price_category. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"price_category":["The price category field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"digital_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for digital release."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"license_type":{"type":"string","example":"copyright","description":"Rights model for the release, such as original, licensed, remix, cover, or another supported catalog type."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"sound_recordings_copyright_year":{"type":"integer","example":2026,"description":"Year associated with the sound recording copyright line for the release."},"sound_recordings_copyright_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name shown on the sound recording copyright line for the release."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."}},"required":["price_category","digital_release_date","license_type","license_holder_year","license_holder_name"]},"example":{"price_category":"mid","digital_release_date":"2026-08-21","original_release_date":"2026-08-21","license_type":"copyright","license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","sound_recordings_copyright_year":2026,"sound_recordings_copyright_name":"Night Shift Records Ltd","territories":["GB","US","DE","NL"]}}}}}},"/api/v1/releases/{release_id}/pre-qc":{"get":{"tags":["Releases"],"summary":"View Release Readiness Checks","operationId":"getReleaseReadinessChecks","description":"Run release readiness checks before submission. The response highlights metadata, rights, artwork, audio, and delivery issues that should be fixed before sending the release to review.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"View Release Readiness Checks succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"passed":{"type":"boolean","example":false,"description":"Whether the readiness or validation check passed."},"checks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","example":"missing_license_date","description":"code for checks."},"severity":{"type":"string","example":"warning","description":"severity for checks."},"message":{"type":"string","example":"Add original release date before submission.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}}},"description":"Readiness, copyright, or validation checks returned for the release or workflow."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"passed":false,"checks":[{"code":"missing_license_date","severity":"warning","message":"Add original release date before submission."}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/releases/{release_id}/submit":{"post":{"tags":["Releases"],"summary":"Submit Release","operationId":"submitRelease","description":"Submit an organization-owned draft release for review after metadata, cover art, tracks, rights, territories, and destinations are complete. The response confirms the next review state or explains blocking readiness issues.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Submit Release succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Release submitted.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Release submitted."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/releases/{release_id}/tracks":{"get":{"tags":["Releases"],"summary":"List Release Tracks","operationId":"listReleaseTracks","description":"List Release Tracks. Use it to draft releases, update metadata, attach artwork and tracks, define rights, choose territories, and prepare releases for review and delivery. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"List Release Tracks succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"track_version":{"type":"string","example":"Original Mix","description":"Version label for the track, such as remix, radio edit, instrumental, or acoustic version."},"isrc_code":{"type":"string","example":"GBSMU2600001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"iswc_code":{"type":"string","example":"T0345246801","description":"ISWC for the composition when available."},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"playback_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri","description":"Public URL returned for this resource or action."},"preview_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","format":"uri","description":"Public URL returned for this resource or action."},"documents_requested":{"type":"boolean","example":false,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"title":"Midnight Atlas","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"},{"artist_id":"28636f32-61a4-41b8-8af4-70813049b9aa","name":"Olivia Smith","type":"Composer"}],"duration":196,"language":"English","primary_genre":"Electronic","secondary_genre":"Ambient","track_version":"Original Mix","isrc_code":"GBSMU2600001","iswc_code":"T0345246801","is_available_separately":true,"is_parental_advisory":false,"license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","playback_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","preview_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","documents_requested":false,"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/releases/{release_id}/tracks/reorder":{"post":{"tags":["Releases"],"summary":"Reorder Release Tracks","operationId":"reorderReleaseTracks","description":"Set the final track order for a release by submitting track_ids in sequence. Use this before release submission so DSP metadata reflects the intended running order.","parameters":[{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Reorder Release Tracks succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Track order updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"track_ids":{"type":"array","items":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid"},"description":"Ordered public track references used to assign, reorder, or split revenue for tracks visible to the organization."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Track order updated.","data":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","track_ids":["e454b6f8-df5b-49db-9b9f-916f74ec1f21","1f46d29e-e1d7-4e66-8e88-7b34d2d2ee49"]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for track_ids. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"track_ids":["Choose a valid audio file or track reference."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"track_ids":{"type":"array","items":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid"},"description":"Ordered public track references used to assign, reorder, or split revenue for tracks visible to the organization."}},"required":["track_ids"]},"example":{"track_ids":["e454b6f8-df5b-49db-9b9f-916f74ec1f21","1f46d29e-e1d7-4e66-8e88-7b34d2d2ee49"]}}}}}},"/api/v1/releases/migrate":{"post":{"tags":["Releases"],"summary":"Import Releases From Music URLs","operationId":"importReleasesFromMusicUrls","description":"Import one or more visible Spotify album or track URLs into draft release records for the authenticated organization. The endpoint applies the same release creation limits and permissions as the dashboard import workflow, returns the imported releases, and never accepts organization selectors.","parameters":[],"responses":{"200":{"description":"Import Releases From Music URLs succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","required":["success","message","data"],"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Release imported successfully."},"data":{"type":"object","required":["releases"],"properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/Release"}}}}}},"example":{"success":true,"message":"Release imported successfully.","data":{"releases":[{"release_id":"7f6d2a4b-8c41-4e2d-9c5e-13a2b7c8d904","title":"Midnight Atlas","status":"draft","created_at":"2026-07-04T10:35:00+00:00","updated_at":"2026-07-04T10:35:00+00:00","cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","artists":[{"artist_id":"2af7f8d8-1f43-46a9-9e92-84e781c8f20d","name":"Nova Vale","country":"GB"}]}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for urls. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"urls":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"urls":{"type":"array","items":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri"},"description":"External catalog, DSP, or distributor URLs that identify the release being migrated into SpaceMedia."},"distributor":{"type":"string","example":"distrokid","description":"Name of the current or previous distributor for the release migration request."}},"required":["urls"]},"example":{"urls":["https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z"],"distributor":"distrokid"}}}}}},"/api/v1/releases/distribution-channels":{"get":{"tags":["Reference Data"],"summary":"List Distribution Channels","operationId":"listReleaseDistributionChannels","description":"List the enabled distribution channels that can be selected for release delivery. Use the stable channel codes in release distribution requests while presenting the public names in client interfaces.","parameters":[],"responses":{"200":{"description":"Enabled release distribution channels returned successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","example":"spotify","description":"Stable delivery-channel code accepted by release distribution requests."},"name":{"type":"string","example":"Spotify","description":"Public display name for the delivery channel."}},"required":["code","name"]},"description":"Enabled delivery channels available to the authenticated organization."}},"required":["success","data"]},"example":{"success":true,"data":[{"code":"spotify","name":"Spotify"},{"code":"apple_music","name":"Apple Music"},{"code":"youtube_music","name":"YouTube Music"}]}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/releases/territories":{"get":{"tags":["Reference Data"],"summary":"List Release Territories","operationId":"listReleaseTerritories","description":"List Release Territories. Use it to fetch stable country, territory, language, and catalog option values before building release, rights, billing, or profile forms. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"List Release Territories succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","example":"WORLDWIDE","description":"Stable public code for a country, territory, permission, package, or status option."},"name":{"type":"string","example":"Worldwide","description":"Display name for this data."}}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":[{"code":"WORLDWIDE","name":"Worldwide"},{"code":"GB","name":"United Kingdom"},{"code":"US","name":"United States"}]}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/smartlinks":{"get":{"tags":["Smartlinks"],"summary":"List Smartlinks","operationId":"listSmartlinks","description":"List Smartlinks. Use it to create and maintain release landing pages, DSP destinations, analytics visibility, and personal or organization smartlink preferences. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"search","in":"query","required":false,"description":"Search term for matching visible records.","schema":{"type":"string","example":"midnight"},"example":"midnight"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20},{"name":"sort","in":"query","required":false,"description":"Sort direction for creation date.","schema":{"type":"string","example":"desc"},"example":"desc"}],"responses":{"200":{"description":"List Smartlinks succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"slug":{"type":"string","example":"nova-vale-midnight-atlas","description":"URL-safe slug used for public links or add-on references."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"public_url":{"type":"string","example":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","format":"uri","description":"Public URL returned for this resource or action."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."},"clicks":{"type":"integer","example":1840,"description":"Number of recorded smartlink clicks for the selected period or destination."},"conversion_rate":{"type":"number","example":0.18,"description":"Percentage of visitors who clicked through or completed the measured smartlink action."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"smartlink_id":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"slug":"nova-vale-midnight-atlas","title":"Midnight Atlas","status":"published","public_url":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","destinations":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","enabled":true},{"platform":"apple_music","url":"https://music.apple.com/gb/album/midnight-atlas/1784529016","enabled":true}],"clicks":1840,"conversion_rate":0.18,"updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for search. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"search":["The search field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Smartlinks"],"summary":"Create Smartlink","operationId":"createSmartlink","description":"Create a release smartlink with slug, title, release reference, and DSP destinations. Use the returned smartlink_id for analytics, preference, and sync calls.","parameters":[],"responses":{"201":{"description":"Create Smartlink created the resource and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Smartlink created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"slug":{"type":"string","example":"nova-vale-midnight-atlas","description":"URL-safe slug used for public links or add-on references."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"public_url":{"type":"string","example":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","format":"uri","description":"Public URL returned for this resource or action."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."},"clicks":{"type":"integer","example":1840,"description":"Number of recorded smartlink clicks for the selected period or destination."},"conversion_rate":{"type":"number","example":0.18,"description":"Percentage of visitors who clicked through or completed the measured smartlink action."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Smartlink created.","data":{"smartlink_id":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"slug":"nova-vale-midnight-atlas","title":"Midnight Atlas","status":"published","public_url":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","destinations":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","enabled":true},{"platform":"apple_music","url":"https://music.apple.com/gb/album/midnight-atlas/1784529016","enabled":true}],"clicks":1840,"conversion_rate":0.18,"updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for release_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"release_id":["Choose a release visible to this organization."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"slug":{"type":"string","example":"nova-vale-midnight-atlas","description":"URL-safe slug used for public links or add-on references."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."}},"required":["release_id","slug","title"]},"example":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","slug":"nova-vale-midnight-atlas","title":"Midnight Atlas","destinations":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","enabled":true},{"platform":"apple_music","url":"https://music.apple.com/gb/album/midnight-atlas/1784529016","enabled":true}]}}}}}},"/api/v1/smartlinks/{smartlink_id}":{"get":{"tags":["Smartlinks"],"summary":"View Smartlink","operationId":"getSmartlink","description":"View Smartlink. Use it to create and maintain release landing pages, DSP destinations, analytics visibility, and personal or organization smartlink preferences. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"View Smartlink succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"slug":{"type":"string","example":"nova-vale-midnight-atlas","description":"URL-safe slug used for public links or add-on references."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"public_url":{"type":"string","example":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","format":"uri","description":"Public URL returned for this resource or action."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."},"clicks":{"type":"integer","example":1840,"description":"Number of recorded smartlink clicks for the selected period or destination."},"conversion_rate":{"type":"number","example":0.18,"description":"Percentage of visitors who clicked through or completed the measured smartlink action."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"smartlink_id":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"slug":"nova-vale-midnight-atlas","title":"Midnight Atlas","status":"published","public_url":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","destinations":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","enabled":true},{"platform":"apple_music","url":"https://music.apple.com/gb/album/midnight-atlas/1784529016","enabled":true}],"clicks":1840,"conversion_rate":0.18,"updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"put":{"tags":["Smartlinks"],"summary":"Update Smartlink","operationId":"updateSmartlink","description":"Replace editable smartlink fields such as title, destination list, or status by smartlink_id. Use this for full smartlink form saves.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"Update Smartlink succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Smartlink updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"slug":{"type":"string","example":"nova-vale-midnight-atlas","description":"URL-safe slug used for public links or add-on references."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"public_url":{"type":"string","example":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","format":"uri","description":"Public URL returned for this resource or action."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."},"clicks":{"type":"integer","example":1840,"description":"Number of recorded smartlink clicks for the selected period or destination."},"conversion_rate":{"type":"number","example":0.18,"description":"Percentage of visitors who clicked through or completed the measured smartlink action."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Smartlink updated.","data":{"smartlink_id":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"slug":"nova-vale-midnight-atlas","title":"Midnight Atlas","status":"published","public_url":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","destinations":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","enabled":true},{"platform":"apple_music","url":"https://music.apple.com/gb/album/midnight-atlas/1784529016","enabled":true}],"clicks":1840,"conversion_rate":0.18,"updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for destinations.0.url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"destinations.0.url":["Enter a valid DSP destination URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."}},"required":["title","destinations"]},"example":{"title":"Midnight Atlas","destinations":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","enabled":true},{"platform":"apple_music","url":"https://music.apple.com/gb/album/midnight-atlas/1784529016","enabled":true}],"status":"published"}}}}},"patch":{"tags":["Smartlinks"],"summary":"Update Smartlink Status","operationId":"updateSmartlinkStatus","description":"Update a small subset of smartlink fields by smartlink_id, such as status changes, without resubmitting the full destination list.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"Update Smartlink Status succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Smartlink updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"slug":{"type":"string","example":"nova-vale-midnight-atlas","description":"URL-safe slug used for public links or add-on references."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"public_url":{"type":"string","example":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","format":"uri","description":"Public URL returned for this resource or action."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."},"clicks":{"type":"integer","example":1840,"description":"Number of recorded smartlink clicks for the selected period or destination."},"conversion_rate":{"type":"number","example":0.18,"description":"Percentage of visitors who clicked through or completed the measured smartlink action."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Smartlink updated.","data":{"smartlink_id":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"slug":"nova-vale-midnight-atlas","title":"Midnight Atlas","status":"published","public_url":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","destinations":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","enabled":true},{"platform":"apple_music","url":"https://music.apple.com/gb/album/midnight-atlas/1784529016","enabled":true}],"clicks":1840,"conversion_rate":0.18,"updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for status. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"status":["Choose a supported status value for this endpoint."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."}},"required":["status"]},"example":{"status":"published"}}}}},"delete":{"tags":["Smartlinks"],"summary":"Delete Smartlink","operationId":"deleteSmartlink","description":"Delete Smartlink. Use it to create and maintain release landing pages, DSP destinations, analytics visibility, and personal or organization smartlink preferences. It removes, revokes, or cancels the target when permissions and resource state allow it, then returns a confirmation or policy error.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"Delete Smartlink succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Smartlink deleted.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Smartlink deleted."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/smartlinks/{smartlink_id}/analytics":{"get":{"tags":["Smartlinks"],"summary":"View Smartlink Analytics","operationId":"getSmartlinkAnalytics","description":"Return analytics for a smartlink by smartlink_id, including organization-visible engagement metrics for release landing page performance.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"View Smartlink Analytics succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"clicks":{"type":"integer","example":1840,"description":"Number of recorded smartlink clicks for the selected period or destination."},"top_destinations":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"platform":{"type":"string","example":"spotify","description":"platform for top_destinations."},"clicks":{"type":"integer","example":970,"description":"clicks for top_destinations."}}},"description":"Highest-performing smartlink destinations for the selected analytics period."},"countries":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","example":"GB","description":"code for countries."},"clicks":{"type":"integer","example":620,"description":"clicks for countries."}}},"description":"Country options available for profile, release, rights, and billing forms."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"smartlink_id":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","clicks":1840,"top_destinations":[{"platform":"spotify","clicks":970},{"platform":"apple_music","clicks":540}],"countries":[{"code":"GB","clicks":620}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/smartlinks/{smartlink_id}/preferences":{"get":{"tags":["Smartlinks"],"summary":"View Smartlink Preferences","operationId":"getSmartlinkPreferences","description":"View Smartlink Preferences. Use it to create and maintain release landing pages, DSP destinations, analytics visibility, and personal or organization smartlink preferences. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"View Smartlink Preferences succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"user_preferences":{"type":"object","additionalProperties":true,"properties":{"default_destination":{"type":"string","example":"spotify","description":"Preferred DSP destination for the authenticated user when opening or managing this smartlink."}},"description":"Smartlink preferences stored for the authenticated user."},"organization_preferences":{"type":"object","additionalProperties":true,"properties":{"show_branding":{"type":"boolean","example":true,"description":"Whether organization branding should be displayed on the smartlink page."},"collect_analytics":{"type":"boolean","example":true,"description":"Whether engagement analytics should be collected for the smartlink when supported by account settings."}},"description":"Smartlink preferences applied across the organization."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"smartlink_id":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","user_preferences":{"default_destination":"spotify"},"organization_preferences":{"show_branding":true,"collect_analytics":true}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/smartlinks/{smartlink_id}/preferences/me":{"put":{"tags":["Smartlinks"],"summary":"Update My Smartlink Preferences","operationId":"updateMySmartlinkPreferences","description":"Update personal defaults for how the authenticated user works with a smartlink, such as default destination preference, without changing organization-wide smartlink settings.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"Update My Smartlink Preferences succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Smartlink preferences updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Smartlink preferences updated."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for default_destination. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"default_destination":["The default destination field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"default_destination":{"type":"string","example":"spotify","description":"Preferred DSP destination for the authenticated user when opening or managing this smartlink."}},"required":["default_destination"]},"example":{"default_destination":"spotify"}}}}}},"/api/v1/smartlinks/{smartlink_id}/preferences/org":{"put":{"tags":["Smartlinks"],"summary":"Update Organization Smartlink Preferences","operationId":"updateOrganizationSmartlinkPreferences","description":"Update organization-wide smartlink preferences by smartlink_id, such as branding visibility and analytics collection settings.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"Update Organization Smartlink Preferences succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Organization smartlink preferences updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Organization smartlink preferences updated."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for show_branding. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"show_branding":["The show branding field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"show_branding":{"type":"boolean","example":true,"description":"Whether organization branding should be displayed on the smartlink page."},"collect_analytics":{"type":"boolean","example":true,"description":"Whether engagement analytics should be collected for the smartlink when supported by account settings."}},"required":["show_branding","collect_analytics"]},"example":{"show_branding":true,"collect_analytics":true}}}}}},"/api/v1/smartlinks/{smartlink_id}/sync":{"post":{"tags":["Smartlinks"],"summary":"Sync Smartlink","operationId":"syncSmartlink","description":"Refresh a smartlink by smartlink_id so destination and release data reflect the latest catalog state visible to the organization.","parameters":[{"name":"smartlink_id","in":"path","required":true,"description":"Public smartlink reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f"}],"responses":{"200":{"description":"Sync Smartlink succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Smartlink synced.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"smartlink_id":{"type":"string","example":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","format":"uuid","description":"Stable public smartlink reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"slug":{"type":"string","example":"nova-vale-midnight-atlas","description":"URL-safe slug used for public links or add-on references."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"public_url":{"type":"string","example":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","format":"uri","description":"Public URL returned for this resource or action."},"destinations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","example":"spotify","description":"Streaming platform or destination key, such as spotify, apple_music, youtube_music, or deezer."},"url":{"type":"string","example":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","format":"uri","description":"Public URL returned for this resource or action."},"enabled":{"type":"boolean","example":true,"description":"Whether this option or destination is currently enabled."}},"required":["platform","url"]},"description":"DSP and landing-page destination objects shown on the smartlink."},"clicks":{"type":"integer","example":1840,"description":"Number of recorded smartlink clicks for the selected period or destination."},"conversion_rate":{"type":"number","example":0.18,"description":"Percentage of visitors who clicked through or completed the measured smartlink action."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Smartlink synced.","data":{"smartlink_id":"1fdf8564-81f7-4607-9c8b-154b62db8d5f","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"slug":"nova-vale-midnight-atlas","title":"Midnight Atlas","status":"published","public_url":"https://links.northstar-distribution.co.uk/nova-vale-midnight-atlas","destinations":[{"platform":"spotify","url":"https://open.spotify.com/album/4Gj9kL2mN8rT6bY1xQvP3z","enabled":true},{"platform":"apple_music","url":"https://music.apple.com/gb/album/midnight-atlas/1784529016","enabled":true}],"clicks":1840,"conversion_rate":0.18,"updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/splits":{"get":{"tags":["Revenue Splits"],"summary":"List Revenue Splits","operationId":"listRevenueSplits","description":"List Revenue Splits. Use it to assign beneficiary shares to releases or tracks, invite collaborators, and manage split confirmation without exposing private accounting records. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"search","in":"query","required":false,"description":"Search term for matching visible records.","schema":{"type":"string","example":"midnight"},"example":"midnight"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20},{"name":"sort","in":"query","required":false,"description":"Sort direction for creation date.","schema":{"type":"string","example":"desc"},"example":"desc"},{"name":"X-User-Id","in":"header","required":false,"description":"Optional user_id to perform an allowed action for a user in the same organization.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"List Revenue Splits succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"split_id":{"type":"string","example":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","format":"uuid","description":"Stable public split reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas Producer Share","description":"Catalog or content title shown in the dashboard and API responses."},"percentage":{"type":"integer","example":25,"description":"Revenue split percentage assigned to this beneficiary."},"start_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for start."},"end_date":{"description":"Calendar date for end.","type":["string","null"],"format":"date"},"locked":{"type":"boolean","example":false,"description":"Whether the split, role, or configuration is locked from further editing in its current state."},"beneficiary":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this beneficiary."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User or collaborator receiving the revenue split share."},"creator":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this creator."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User summary for the person who created the record."},"releases":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}}},"description":"Releases visible for the current organization and permission scope."},"tracks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."}}},"description":"Tracks included in the release or returned by the catalog query."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"split_id":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","title":"Midnight Atlas Producer Share","percentage":25,"start_date":"2026-08-21","end_date":null,"locked":false,"beneficiary":{"user_id":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","name":"Eli Brooks","email":"eli.brooks@northstar-distribution.co.uk"},"creator":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"releases":[{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}],"tracks":[{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","title":"Midnight Atlas"}]}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for search. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"search":["The search field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Revenue Splits"],"summary":"Create Revenue Split","operationId":"createRevenueSplit","description":"Create a revenue split by assigning a beneficiary, percentage, dates, and release or track references. Use beneficiary_id for an existing organization user, beneficiary_email for an existing user by email, or email to invite a new beneficiary.","parameters":[{"name":"X-User-Id","in":"header","required":true,"description":"Required user_id for catalog ownership and quota context. The client must also have users:act-as.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"Create Revenue Split succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Revenue split created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"split_id":{"type":"string","example":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","format":"uuid","description":"Stable public split reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas Producer Share","description":"Catalog or content title shown in the dashboard and API responses."},"percentage":{"type":"integer","example":25,"description":"Revenue split percentage assigned to this beneficiary."},"start_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for start."},"end_date":{"description":"Calendar date for end.","type":["string","null"],"format":"date"},"locked":{"type":"boolean","example":false,"description":"Whether the split, role, or configuration is locked from further editing in its current state."},"beneficiary":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this beneficiary."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User or collaborator receiving the revenue split share."},"creator":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this creator."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User summary for the person who created the record."},"releases":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}}},"description":"Releases visible for the current organization and permission scope."},"tracks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."}}},"description":"Tracks included in the release or returned by the catalog query."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Revenue split created.","data":{"split_id":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","title":"Midnight Atlas Producer Share","percentage":25,"start_date":"2026-08-21","end_date":null,"locked":false,"beneficiary":{"user_id":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","name":"Eli Brooks","email":"eli.brooks@northstar-distribution.co.uk"},"creator":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"releases":[{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}],"tracks":[{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","title":"Midnight Atlas"}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for percentage. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"percentage":["Enter a revenue split percentage between 0.01 and 100."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","example":"Midnight Atlas Producer Share","description":"Catalog or content title shown in the dashboard and API responses."},"beneficiary_id":{"type":"string","example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","format":"uuid","description":"Public user reference for an existing organization user who should receive this split."},"percentage":{"type":"integer","example":25,"description":"Revenue split percentage assigned to this beneficiary."},"start_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for start."},"release_ids":{"type":"array","items":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid"},"description":"Public release references used to assign a split or filter a workflow to organization-visible releases."},"track_ids":{"type":"array","items":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid"},"description":"Ordered public track references used to assign, reorder, or split revenue for tracks visible to the organization."},"beneficiary_email":{"type":"string","format":"email","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address of an existing organization user who should receive this split."},"email":{"type":"string","format":"email","example":"riley.stone@northstar-distribution.co.uk","description":"Email address to invite as a new split beneficiary when the person is not yet an organization user."}},"required":["title","percentage"],"oneOf":[{"required":["beneficiary_id"]},{"required":["beneficiary_email"]},{"required":["email"]}]},"example":{"title":"Midnight Atlas Producer Share","beneficiary_id":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","percentage":25,"start_date":"2026-08-21","release_ids":["b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"],"track_ids":["e454b6f8-df5b-49db-9b9f-916f74ec1f21"]}}}}}},"/api/v1/splits/{split_id}":{"post":{"tags":["Revenue Splits"],"summary":"Update Revenue Split","operationId":"updateRevenueSplit","description":"Update a revenue split by split_id, including percentage, date, and release assignment changes that are allowed by the split state.","parameters":[{"name":"split_id","in":"path","required":true,"description":"Public split reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47"}],"responses":{"200":{"description":"Update Revenue Split succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Revenue split updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"split_id":{"type":"string","example":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","format":"uuid","description":"Stable public split reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas Producer Share","description":"Catalog or content title shown in the dashboard and API responses."},"percentage":{"type":"integer","example":30,"description":"Revenue split percentage assigned to this beneficiary."},"start_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for start."},"end_date":{"description":"Calendar date for end.","type":["string","null"],"format":"date"},"locked":{"type":"boolean","example":false,"description":"Whether the split, role, or configuration is locked from further editing in its current state."},"beneficiary":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this beneficiary."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User or collaborator receiving the revenue split share."},"creator":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this creator."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User summary for the person who created the record."},"releases":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}}},"description":"Releases visible for the current organization and permission scope."},"tracks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."}}},"description":"Tracks included in the release or returned by the catalog query."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Revenue split updated.","data":{"split_id":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","title":"Midnight Atlas Producer Share","percentage":30,"start_date":"2026-08-21","end_date":null,"locked":false,"beneficiary":{"user_id":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","name":"Eli Brooks","email":"eli.brooks@northstar-distribution.co.uk"},"creator":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"releases":[{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}],"tracks":[{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","title":"Midnight Atlas"}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for release_ids.0. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"release_ids.0":["Choose a release visible to this organization."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","example":"Midnight Atlas Producer Share","description":"Catalog or content title shown in the dashboard and API responses."},"percentage":{"type":"integer","example":30,"description":"Revenue split percentage assigned to this beneficiary."},"start_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for start."},"release_ids":{"type":"array","items":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid"},"description":"Public release references used to assign a split or filter a workflow to organization-visible releases."}},"required":["title","percentage"]},"example":{"title":"Midnight Atlas Producer Share","percentage":30,"start_date":"2026-08-21","release_ids":["b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"]}}}}}},"/api/v1/splits/{split_id}/confirm":{"post":{"tags":["Revenue Splits"],"summary":"Confirm Revenue Split","operationId":"confirmRevenueSplit","description":"Confirm participation in a revenue split by split_id. Use this when an invited or existing beneficiary accepts the split terms.","parameters":[{"name":"split_id","in":"path","required":true,"description":"Public split reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47"}],"responses":{"200":{"description":"Confirm Revenue Split succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Revenue split confirmed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"split_id":{"type":"string","example":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","format":"uuid","description":"Stable public split reference. Use this value in related endpoint paths and request bodies."},"confirmed":{"type":"boolean","example":true,"description":"Whether the split, invitation, checkout, or action has been confirmed."},"confirmed_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when confirmed occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Revenue split confirmed.","data":{"split_id":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","confirmed":true,"confirmed_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/subscriptions":{"get":{"tags":["Billing and Checkouts"],"summary":"List Subscriptions","operationId":"listSubscriptions","description":"List Subscriptions. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"List Subscriptions succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"subscription_id":{"type":"string","example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","format":"uuid","description":"Stable public subscription reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"is_active":{"type":"boolean","example":true,"description":"Whether the subscription, plan, add-on, or resource is currently active."},"package":{"type":"object","additionalProperties":true,"properties":{"package_id":{"type":"string","example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","format":"uuid","description":"Stable public package reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Growth Distribution Monthly","description":"Display name for this package."},"type":{"type":"string","example":"membership","description":"Public type or role value for this item."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"price":{"type":"integer","example":49,"description":"price for package."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"royalty_percentage":{"type":"integer","example":85,"description":"royalty percentage for package."},"artist_profile_limit":{"type":"integer","example":25,"description":"artist profile limit for package."},"release_limit":{"type":"integer","example":50,"description":"release limit for package."},"release_limit_cycle":{"type":"string","example":"monthly","description":"release limit cycle for package."},"feature_list":{"type":"array","items":{"type":"string","example":"Unlimited team members"},"description":"feature list for package."}},"description":"Membership package attached to the subscription or checkout."},"subscribed_at":{"type":"string","example":"2026-06-01T09:00:00+00:00","format":"date-time","description":"Timestamp for when subscribed occurred, formatted as ISO 8601 when available."},"next_payment":{"type":"string","example":"2026-08-01T09:00:00+00:00","format":"date-time","description":"Next scheduled payment date for the subscription when available."},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"total_paid_amount":{"type":"integer","example":98,"description":"Monetary amount in the currency shown on the same object."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"subscription_id":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","status":"active","is_active":true,"package":{"package_id":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","name":"Growth Distribution Monthly","type":"membership","status":"published","price":49,"currency":"GBP","royalty_percentage":85,"artist_profile_limit":25,"release_limit":50,"release_limit_cycle":"monthly","feature_list":["Unlimited team members","Priority delivery review","Advanced catalog reporting"]},"subscribed_at":"2026-06-01T09:00:00+00:00","next_payment":"2026-08-01T09:00:00+00:00","amount":49,"total_paid_amount":98,"gateway":"stripe"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/subscriptions/{subscription_id}/cancel":{"post":{"tags":["Billing and Checkouts"],"summary":"Cancel Subscription","operationId":"cancelSubscription","description":"Cancel Subscription. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"subscription_id","in":"path","required":true,"description":"Public subscription reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d"}],"responses":{"200":{"description":"Cancel Subscription succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Subscription cancelled.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Subscription cancelled."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/subscriptions/{subscription_id}/resume":{"post":{"tags":["Billing and Checkouts"],"summary":"Resume Subscription","operationId":"resumeSubscription","description":"Resume Subscription. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"subscription_id","in":"path","required":true,"description":"Public subscription reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d"}],"responses":{"200":{"description":"Resume Subscription succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Subscription resumed.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Subscription resumed."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/subscriptions/subscribe/{package_id}/checkout/airwallex":{"post":{"tags":["Billing and Checkouts"],"summary":"Create Airwallex Subscription Checkout","operationId":"createAirwallexSubscriptionCheckout","description":"Create Airwallex Subscription Checkout. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"package_id","in":"path","required":true,"description":"Public package reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6"}],"responses":{"200":{"description":"Create Airwallex Subscription Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"airwallex","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"embedded_checkout_token":{"type":"string","example":"docs_invalid_embedded_checkout_token","description":"Short-lived embedded checkout token. Treat this value as sensitive payment data and never log it or expose it in support tickets.","format":"password","x-sensitive":true},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","format":"date-time","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"airwallex","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","embedded_checkout_token":"docs_invalid_embedded_checkout_token","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for success_url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"success_url":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["success_url","cancel_url"]},"example":{"success_url":"https://northstar-distribution.co.uk/billing/success","cancel_url":"https://northstar-distribution.co.uk/billing/cancel"}}}}}},"/api/v1/subscriptions/subscribe/{package_id}/checkout/paypal":{"post":{"tags":["Billing and Checkouts"],"summary":"Create PayPal Subscription Checkout","operationId":"createPaypalSubscriptionCheckout","description":"Create PayPal Subscription Checkout. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"package_id","in":"path","required":true,"description":"Public package reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6"}],"responses":{"200":{"description":"Create PayPal Subscription Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"paypal","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"paypal","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"},"description":"Primary response payload for this request."}},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"paypal","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"paypal","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for success_url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"success_url":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["success_url","cancel_url"]},"example":{"success_url":"https://northstar-distribution.co.uk/billing/success","cancel_url":"https://northstar-distribution.co.uk/billing/cancel"}}}}}},"/api/v1/subscriptions/subscribe/{package_id}/checkout/stripe":{"post":{"tags":["Billing and Checkouts"],"summary":"Create Stripe Subscription Checkout","operationId":"createStripeSubscriptionCheckout","description":"Create Stripe Subscription Checkout. Use it to start checkouts, verify completion, manage saved payment methods, inspect invoices, and cancel or resume organization billing subscriptions. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[{"name":"package_id","in":"path","required":true,"description":"Public package reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6"}],"responses":{"200":{"description":"Create Stripe Subscription Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Checkout created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]},"status":{"type":"string","example":"pending","description":"Current lifecycle status for this record."},"redirect_url":{"type":"string","example":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","format":"uri","description":"Hosted checkout or management URL where the user should continue the flow."},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"expires_at":{"type":"string","example":"2026-07-04T10:30:00+00:00","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"stripe","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"},"description":"Primary response payload for this request."}},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"stripe","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}},"required":["success","message","data"]},"example":{"success":true,"message":"Checkout created.","data":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1","gateway":"stripe","status":"pending","redirect_url":"https://checkout.spacemedia-docs.invalid/session/docs-checkout-session","amount":49,"currency":"GBP","expires_at":"2026-07-04T10:30:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for success_url. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"success_url":["Enter a valid HTTPS URL."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/success","format":"uri","description":"Public URL returned for this resource or action."},"cancel_url":{"type":"string","example":"https://northstar-distribution.co.uk/billing/cancel","format":"uri","description":"Public URL returned for this resource or action."}},"required":["success_url","cancel_url"]},"example":{"success_url":"https://northstar-distribution.co.uk/billing/success","cancel_url":"https://northstar-distribution.co.uk/billing/cancel"}}}}}},"/api/v1/subscriptions/subscribe/{package_id}/payment-verify":{"post":{"tags":["Billing and Checkouts"],"summary":"Verify Subscription Checkout","operationId":"verifySubscriptionCheckout","description":"Verify a subscription checkout by checkout_id after payment completion. The response confirms whether the subscription was activated or updated.","parameters":[{"name":"package_id","in":"path","required":true,"description":"Public package reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6"}],"responses":{"200":{"description":"Verify Subscription Checkout succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Subscription checkout verified.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"subscription_id":{"type":"string","example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","format":"uuid","description":"Stable public subscription reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"is_active":{"type":"boolean","example":true,"description":"Whether the subscription, plan, add-on, or resource is currently active."},"package":{"type":"object","additionalProperties":true,"properties":{"package_id":{"type":"string","example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","format":"uuid","description":"Stable public package reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Growth Distribution Monthly","description":"Display name for this package."},"type":{"type":"string","example":"membership","description":"Public type or role value for this item."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"price":{"type":"integer","example":49,"description":"price for package."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"royalty_percentage":{"type":"integer","example":85,"description":"royalty percentage for package."},"artist_profile_limit":{"type":"integer","example":25,"description":"artist profile limit for package."},"release_limit":{"type":"integer","example":50,"description":"release limit for package."},"release_limit_cycle":{"type":"string","example":"monthly","description":"release limit cycle for package."},"feature_list":{"type":"array","items":{"type":"string","example":"Unlimited team members"},"description":"feature list for package."}},"description":"Membership package attached to the subscription or checkout."},"subscribed_at":{"type":"string","example":"2026-06-01T09:00:00+00:00","format":"date-time","description":"Timestamp for when subscribed occurred, formatted as ISO 8601 when available."},"next_payment":{"type":"string","example":"2026-08-01T09:00:00+00:00","format":"date-time","description":"Next scheduled payment date for the subscription when available."},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"total_paid_amount":{"type":"integer","example":98,"description":"Monetary amount in the currency shown on the same object."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Subscription checkout verified.","data":{"subscription_id":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","status":"active","is_active":true,"package":{"package_id":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","name":"Growth Distribution Monthly","type":"membership","status":"published","price":49,"currency":"GBP","royalty_percentage":85,"artist_profile_limit":25,"release_limit":50,"release_limit_cycle":"monthly","feature_list":["Unlimited team members","Priority delivery review","Advanced catalog reporting"]},"subscribed_at":"2026-06-01T09:00:00+00:00","next_payment":"2026-08-01T09:00:00+00:00","amount":49,"total_paid_amount":98,"gateway":"stripe"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for checkout_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"checkout_id":["The checkout id field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"checkout_id":{"type":"string","example":"39b189c1-8f8e-4df2-8632-176f87f791a1","format":"uuid","description":"Stable public checkout reference. Use this value in related endpoint paths and request bodies."}},"required":["checkout_id"]},"example":{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1"}}}}}},"/api/v1/theme-editor/draft":{"post":{"tags":["Theme Editor"],"summary":"Save Theme Draft","operationId":"saveThemeDraft","description":"Save Theme Draft. Use it to save, inspect, and publish organization visual branding drafts for the account experience. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Save Theme Draft succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Theme draft saved.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"brand_name":{"type":"string","example":"Northstar Distribution","description":"Organization brand name shown on customer-facing pages and branded account surfaces."},"site_title":{"type":"string","example":"Northstar Distribution Portal","description":"Organization display title shown in branded account surfaces."},"logo_url":{"type":"string","example":"https://assets.spacemedia-docs.invalid/brands/northstar-records/logo.svg","format":"uri","description":"Public URL returned for this resource or action."},"primary_color":{"type":"string","example":"#111827","description":"Primary brand color as a hex value used for prominent buttons, links, and branded surfaces."},"accent_color":{"type":"string","example":"#2DD4BF","description":"Secondary brand color as a hex value used for highlights and supporting UI elements."},"mode":{"type":"string","example":"draft","description":"Mode used by the workflow, such as hosted checkout, embedded checkout, draft, preview, or published state."},"last_published_at":{"type":"string","example":"2026-06-28T16:10:00+00:00","format":"date-time","description":"Timestamp for when last published occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Theme draft saved.","data":{"brand_name":"Northstar Distribution","site_title":"Northstar Distribution Portal","logo_url":"https://assets.spacemedia-docs.invalid/brands/northstar-records/logo.svg","primary_color":"#111827","accent_color":"#2DD4BF","mode":"draft","last_published_at":"2026-06-28T16:10:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for primary_color. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"primary_color":["The primary color field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"primary_color":{"type":"string","example":"#111827","description":"Primary brand color as a hex value used for prominent buttons, links, and branded surfaces."},"accent_color":{"type":"string","example":"#2DD4BF","description":"Secondary brand color as a hex value used for highlights and supporting UI elements."},"logo_url":{"type":"string","example":"https://assets.spacemedia-docs.invalid/brands/northstar-records/logo.svg","format":"uri","description":"Public URL returned for this resource or action."},"site_title":{"type":"string","example":"Northstar Distribution Portal","description":"Organization display title shown in branded account surfaces."}},"required":["primary_color","accent_color","site_title"]},"example":{"primary_color":"#111827","accent_color":"#2DD4BF","logo_url":"https://assets.spacemedia-docs.invalid/brands/northstar-records/logo.svg","site_title":"Northstar Distribution Portal"}}}}}},"/api/v1/theme-editor/profile":{"get":{"tags":["Theme Editor"],"summary":"View Theme Profile","operationId":"getThemeEditorProfile","description":"View Theme Profile. Use it to save, inspect, and publish organization visual branding drafts for the account experience. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[],"responses":{"200":{"description":"View Theme Profile succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"brand_name":{"type":"string","example":"Northstar Distribution","description":"Organization brand name shown on customer-facing pages and branded account surfaces."},"site_title":{"type":"string","example":"Northstar Distribution Portal","description":"Organization display title shown in branded account surfaces."},"logo_url":{"type":"string","example":"https://assets.spacemedia-docs.invalid/brands/northstar-records/logo.svg","format":"uri","description":"Public URL returned for this resource or action."},"primary_color":{"type":"string","example":"#111827","description":"Primary brand color as a hex value used for prominent buttons, links, and branded surfaces."},"accent_color":{"type":"string","example":"#2DD4BF","description":"Secondary brand color as a hex value used for highlights and supporting UI elements."},"mode":{"type":"string","example":"draft","description":"Mode used by the workflow, such as hosted checkout, embedded checkout, draft, preview, or published state."},"last_published_at":{"type":"string","example":"2026-06-28T16:10:00+00:00","format":"date-time","description":"Timestamp for when last published occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"brand_name":"Northstar Distribution","site_title":"Northstar Distribution Portal","logo_url":"https://assets.spacemedia-docs.invalid/brands/northstar-records/logo.svg","primary_color":"#111827","accent_color":"#2DD4BF","mode":"draft","last_published_at":"2026-06-28T16:10:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/theme-editor/publish":{"post":{"tags":["Theme Editor"],"summary":"Publish Theme Profile","operationId":"publishThemeProfile","description":"Publish Theme Profile. Use it to save, inspect, and publish organization visual branding drafts for the account experience. It applies the requested change and returns the updated resource, validation result, or action status needed for the next API step.","parameters":[],"responses":{"200":{"description":"Publish Theme Profile succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Theme profile published.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"brand_name":{"type":"string","example":"Northstar Distribution","description":"Organization brand name shown on customer-facing pages and branded account surfaces."},"site_title":{"type":"string","example":"Northstar Distribution Portal","description":"Organization display title shown in branded account surfaces."},"logo_url":{"type":"string","example":"https://assets.spacemedia-docs.invalid/brands/northstar-records/logo.svg","format":"uri","description":"Public URL returned for this resource or action."},"primary_color":{"type":"string","example":"#111827","description":"Primary brand color as a hex value used for prominent buttons, links, and branded surfaces."},"accent_color":{"type":"string","example":"#2DD4BF","description":"Secondary brand color as a hex value used for highlights and supporting UI elements."},"mode":{"type":"string","example":"published","description":"Mode used by the workflow, such as hosted checkout, embedded checkout, draft, preview, or published state."},"last_published_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last published occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Theme profile published.","data":{"brand_name":"Northstar Distribution","site_title":"Northstar Distribution Portal","logo_url":"https://assets.spacemedia-docs.invalid/brands/northstar-records/logo.svg","primary_color":"#111827","accent_color":"#2DD4BF","mode":"published","last_published_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/integrations/wordpress/oauth/register":{"x-independent-auth":true,"post":{"tags":["WordPress OAuth"],"summary":"Register a WordPress Installation","operationId":"registerWordPressOAuthInstallation","description":"Register a WordPress installation after SpaceMedia verifies a one-time challenge on the same public HTTPS host. Registration returns a public client identifier and never requires or returns a client secret.","security":[],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_url","redirect_uri","challenge","challenge_url"],"properties":{"site_url":{"type":"string","format":"uri","description":"Canonical public HTTPS URL of the WordPress site."},"redirect_uri":{"type":"string","format":"uri","description":"Plugin callback URL on the same host as site_url."},"challenge":{"type":"string","minLength":64,"maxLength":64,"description":"One-time verification value exposed by challenge_url."},"challenge_url":{"type":"string","format":"uri","description":"Public plugin verification endpoint on the same host."},"plugin_version":{"type":["string","null"],"maxLength":30}}},"example":{"site_url":"https://music.example.invalid","redirect_uri":"https://music.example.invalid/wp-admin/admin-post.php?action=spacemedia_oauth_callback","challenge":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","challenge_url":"https://music.example.invalid/wp-json/spacemedia/v1/oauth/challenge","plugin_version":"1.0.0"}}}},"responses":{"201":{"description":"The verified installation was registered and its OAuth endpoint metadata was returned.","content":{"application/json":{"schema":{"type":"object","required":["client_id","authorization_endpoint","token_endpoint","catalog_endpoint","revoke_endpoint"],"properties":{"client_id":{"type":"string"},"authorization_endpoint":{"type":"string","format":"uri"},"token_endpoint":{"type":"string","format":"uri"},"catalog_endpoint":{"type":"string","format":"uri"},"revoke_endpoint":{"type":"string","format":"uri"}}},"example":{"client_id":"docs_wordpress_client","authorization_endpoint":"https://staging.spacemedia.uk/api/v1/integrations/wordpress/oauth/authorize","token_endpoint":"https://staging.spacemedia.uk/api/v1/integrations/wordpress/oauth/token","catalog_endpoint":"https://staging.spacemedia.uk/api/v1/integrations/wordpress/oauth/catalog","revoke_endpoint":"https://staging.spacemedia.uk/api/v1/integrations/wordpress/oauth/revoke"}}}},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/integrations/wordpress/oauth/authorize":{"x-independent-auth":true,"get":{"tags":["WordPress OAuth"],"summary":"Review WordPress Catalog Access","operationId":"showWordPressOAuthAuthorization","description":"Open the authenticated SpaceMedia consent screen for a registered WordPress installation. The request requires an active browser session and uses OAuth state plus PKCE S256 to bind the callback securely.","security":[],"parameters":[{"name":"response_type","in":"query","required":true,"schema":{"type":"string","const":"code"}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string","format":"uri"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","const":"catalog.read"}},{"name":"state","in":"query","required":true,"schema":{"type":"string","maxLength":200}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string","minLength":43,"maxLength":43}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"type":"string","const":"S256"}}],"responses":{"200":{"description":"Authenticated HTML consent screen for the registered installation.","content":{"text/html":{"schema":{"type":"string"},"example":"<!doctype html><html><body>WordPress catalog access consent</body></html>"}}},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["WordPress OAuth"],"summary":"Approve or Deny WordPress Catalog Access","operationId":"decideWordPressOAuthAuthorization","description":"Approve or deny the pending read-only catalog request in an authenticated SpaceMedia browser session. Approval creates a single-use authorization code that expires after ten minutes and is returned only to the registered callback.","security":[],"parameters":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["response_type","client_id","redirect_uri","scope","state","code_challenge","code_challenge_method","decision"],"properties":{"response_type":{"type":"string","const":"code"},"client_id":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"scope":{"type":"string","const":"catalog.read"},"state":{"type":"string"},"code_challenge":{"type":"string"},"code_challenge_method":{"type":"string","const":"S256"},"decision":{"type":"string","enum":["approve","deny"]}}},"example":{"response_type":"code","client_id":"docs_wordpress_client","redirect_uri":"https://music.example.invalid/wp-admin/admin-post.php?action=spacemedia_oauth_callback","scope":"catalog.read","state":"docs_random_state","code_challenge":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","code_challenge_method":"S256","decision":"approve"}}}},"responses":{"302":{"description":"Redirect to the registered callback with code and state, or with access_denied and state."},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/integrations/wordpress/oauth/token":{"x-independent-auth":true,"post":{"tags":["WordPress OAuth"],"summary":"Exchange or Refresh a WordPress OAuth Token","operationId":"exchangeWordPressOAuthToken","description":"Exchange a single-use authorization code and PKCE verifier, or rotate a valid refresh token. Access tokens expire after fifteen minutes, refresh tokens rotate on every use, and token responses must never be cached or logged.","security":[],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["grant_type","client_id","code","code_verifier","redirect_uri"],"properties":{"grant_type":{"type":"string","const":"authorization_code"},"client_id":{"type":"string"},"code":{"type":"string"},"code_verifier":{"type":"string","minLength":43,"maxLength":128},"redirect_uri":{"type":"string","format":"uri"}}},{"type":"object","required":["grant_type","client_id","refresh_token"],"properties":{"grant_type":{"type":"string","const":"refresh_token"},"client_id":{"type":"string"},"refresh_token":{"type":"string"}}}]},"example":{"grant_type":"authorization_code","client_id":"docs_wordpress_client","code":"docs_single_use_code","code_verifier":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","redirect_uri":"https://music.example.invalid/wp-admin/admin-post.php?action=spacemedia_oauth_callback"}}}},"responses":{"200":{"description":"A new access token and rotating refresh token were issued with no-store caching.","content":{"application/json":{"schema":{"type":"object","required":["token_type","access_token","expires_in","refresh_token","scope","account_label"],"properties":{"token_type":{"type":"string","const":"Bearer"},"access_token":{"type":"string"},"expires_in":{"type":"integer","const":900},"refresh_token":{"type":"string"},"scope":{"type":"string","const":"catalog.read"},"account_label":{"type":"string"}}},"example":{"token_type":"Bearer","access_token":"docs_wordpress_access_token","expires_in":900,"refresh_token":"docs_wordpress_refresh_token","scope":"catalog.read","account_label":"Example Catalog Manager"}}}},"400":{"description":"The grant type, authorization code, PKCE verifier, or refresh token is invalid."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/integrations/wordpress/oauth/catalog":{"x-independent-auth":true,"get":{"tags":["WordPress OAuth"],"summary":"Read the Authorized WordPress Catalog","operationId":"getWordPressOAuthCatalog","description":"Return the authorized organization or user catalog as bounded release pages for the WordPress plugin. The endpoint is read-only, exposes public catalog references, and accepts only a short-lived WordPress OAuth bearer token.","security":[{"WordPressOAuthBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"A bounded page of authorized releases and tracks was returned.","content":{"application/json":{"schema":{"type":"object","required":["releases","page","has_more","total"],"properties":{"releases":{"type":"array","items":{"type":"object","additionalProperties":true}},"page":{"type":"integer"},"has_more":{"type":"boolean"},"total":{"type":"integer"}}},"example":{"releases":[{"id":"7da47646-3011-43f8-b497-8a5b1bc2d546","title":"Midnight Signals","artist":"Example Artist","tracks":[{"id":"2d18b418-76ae-4a3a-818d-74b17834b080","title":"Northbound"}]}],"page":1,"has_more":false,"total":1}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/integrations/wordpress/oauth/revoke":{"x-independent-auth":true,"post":{"tags":["WordPress OAuth"],"summary":"Revoke WordPress Catalog Access","operationId":"revokeWordPressOAuthConnection","description":"Revoke the current WordPress installation connection and invalidate its access and refresh tokens. The operation is scoped by the presented short-lived WordPress OAuth bearer token and returns no secret material.","security":[{"WordPressOAuthBearer":[]}],"parameters":[],"responses":{"200":{"description":"The WordPress OAuth connection and its tokens were revoked.","content":{"application/json":{"schema":{"type":"object","required":["revoked"],"properties":{"revoked":{"type":"boolean","const":true}}},"example":{"revoked":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/token":{"post":{"tags":["Authentication"],"summary":"Create API Token","operationId":"createApiToken","description":"Exchange organization API credentials for a bearer token. Store the returned access_token securely, send it in the Authorization header, and refresh it before expires_at instead of retrying failed protected calls.","parameters":[{"name":"X-Api-Key","in":"header","required":true,"description":"Organization API key.","schema":{"type":"string"},"example":"00000000-0000-4000-8000-000000000000"},{"name":"X-Api-Secret","in":"header","required":true,"description":"Organization API secret. Never expose this in browser code.","schema":{"type":"string"},"example":"0000000000000000000000000000000000000000"}],"responses":{"200":{"description":"Access token created.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"access_token":{"type":"string","example":"0000000000000000000000000000000000000000963fbb8e","description":"Bearer token used to authenticate protected Enterprise API requests."},"token_type":{"type":"string","example":"Bearer","description":"Authentication scheme to use with the returned access token."},"expires_at":{"type":"string","format":"date-time","example":"2026-07-04T11:30:00+00:00","description":"Timestamp for when expires occurred, formatted as ISO 8601 when available."}},"example":{"access_token":"0000000000000000000000000000000000000000963fbb8e","token_type":"Bearer","expires_at":"2026-07-04T11:30:00+00:00"},"description":"Primary response payload for this request."}},"example":{"success":true,"data":{"access_token":"0000000000000000000000000000000000000000963fbb8e","token_type":"Bearer","expires_at":"2026-07-04T11:30:00+00:00"}},"required":["success","data"]},"example":{"success":true,"data":{"access_token":"0000000000000000000000000000000000000000963fbb8e","token_type":"Bearer","expires_at":"2026-07-04T11:30:00+00:00"}}}}},"401":{"description":"Invalid API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Invalid API key or secret."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[]}},"/api/v1/tracks":{"get":{"tags":["Tracks"],"summary":"List Tracks","operationId":"listTracks","description":"List Tracks. Use it to upload audio, maintain track metadata, manage contributor and rights information, attach documents, and assign tracks to visible releases. It returns public references and organization-visible fields only, so clients can safely use returned values in follow-up API calls.","parameters":[{"name":"search","in":"query","required":false,"description":"Search term for matching visible records.","schema":{"type":"string","example":"midnight"},"example":"midnight"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20},{"name":"sort","in":"query","required":false,"description":"Sort direction for creation date.","schema":{"type":"string","example":"desc"},"example":"desc"},{"name":"X-User-Id","in":"header","required":false,"description":"Optional user_id to perform an allowed action for a user in the same organization.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"List Tracks succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"track_version":{"type":"string","example":"Original Mix","description":"Version label for the track, such as remix, radio edit, instrumental, or acoustic version."},"isrc_code":{"type":"string","example":"GBSMU2600001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"iswc_code":{"type":"string","example":"T0345246801","description":"ISWC for the composition when available."},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"playback_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri","description":"Public URL returned for this resource or action."},"preview_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","format":"uri","description":"Public URL returned for this resource or action."},"documents_requested":{"type":"boolean","example":false,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"title":"Midnight Atlas","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"},{"artist_id":"28636f32-61a4-41b8-8af4-70813049b9aa","name":"Olivia Smith","type":"Composer"}],"duration":196,"language":"English","primary_genre":"Electronic","secondary_genre":"Ambient","track_version":"Original Mix","isrc_code":"GBSMU2600001","iswc_code":"T0345246801","is_available_separately":true,"is_parental_advisory":false,"license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","playback_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","preview_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","documents_requested":false,"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for search. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"search":["The search field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Tracks"],"summary":"Create Track","operationId":"createTrack","description":"Create a track from audio_file_id plus title, artists, language, genre, rights, identifiers, lyrics, and availability metadata. The response returns the stable track_id for release assignment.","parameters":[{"name":"X-User-Id","in":"header","required":true,"description":"Required user_id for catalog ownership and quota context. The client must also have users:act-as.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"Create Track succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Track created.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"track_version":{"type":"string","example":"Original Mix","description":"Version label for the track, such as remix, radio edit, instrumental, or acoustic version."},"isrc_code":{"type":"string","example":"GBSMU2600001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"iswc_code":{"type":"string","example":"T0345246801","description":"ISWC for the composition when available."},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"playback_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri","description":"Public URL returned for this resource or action."},"preview_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","format":"uri","description":"Public URL returned for this resource or action."},"documents_requested":{"type":"boolean","example":false,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Track created.","data":{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"title":"Midnight Atlas","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"},{"artist_id":"28636f32-61a4-41b8-8af4-70813049b9aa","name":"Olivia Smith","type":"Composer"}],"duration":196,"language":"English","primary_genre":"Electronic","secondary_genre":"Ambient","track_version":"Original Mix","isrc_code":"GBSMU2600001","iswc_code":"T0345246801","is_available_separately":true,"is_parental_advisory":false,"license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","playback_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","preview_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","documents_requested":false,"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for audio_file_id. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"audio_file_id":["Use an audio_file_id returned by the track upload endpoint."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"release_id":{"type":"string","format":"uuid","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","description":"Public release reference returned by the releases API. Include it when the new track belongs to a release."},"audio_file_id":{"type":"string","example":"audio_1783157400_6f9c2b8e4d1a","description":"Temporary audio upload reference returned by the upload endpoint."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"iswc_code":{"type":"string","example":"T-034.524.680-1","description":"ISWC for the composition when available."},"isrc_code":{"type":"string","example":"GB-SMU-26-00001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"lyrics":{"description":"Lyrics text when supplied for the track.","type":["string","null"]},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"notes":{"type":"string","example":"Original mix for DSP delivery.","description":"Operational notes visible to permitted organization users during review."},"metadata":{"type":"object","additionalProperties":true,"properties":{"version":{"type":"string","example":"Original Mix","description":"version for metadata."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."}},"description":"Additional structured metadata for this resource."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"links":{"type":"array","items":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri"},"description":"External reference links for the track, such as preview, lyric, rights, or platform URLs relevant to catalog review."}},"required":["title","audio_file_id","artists","language","license_holder_year","license_holder_name","links"]},"example":{"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","primary_genre":"Electronic","iswc_code":"T-034.524.680-1","isrc_code":"GB-SMU-26-00001","lyrics":null,"is_available_separately":true,"is_parental_advisory":false,"license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","notes":"Original mix for DSP delivery.","metadata":{"version":"Original Mix","secondary_genre":"Ambient"},"duration":196,"links":["https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav"]}}}}}},"/api/v1/tracks/{track_id}":{"post":{"tags":["Tracks"],"summary":"Update Track","operationId":"updateTrack","description":"Update track metadata, audio reference, rights, identifiers, lyrics, and platform links by track_id. Only tracks visible to the organization can be changed.","parameters":[{"name":"track_id","in":"path","required":true,"description":"Public track reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21"},{"name":"X-User-Id","in":"header","required":true,"description":"Required user_id for catalog ownership and quota context. The client must also have users:act-as.","schema":{"type":"string","format":"uuid"},"example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c"}],"responses":{"200":{"description":"Update Track succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Track updated.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"track_version":{"type":"string","example":"Original Mix","description":"Version label for the track, such as remix, radio edit, instrumental, or acoustic version."},"isrc_code":{"type":"string","example":"GBSMU2600001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"iswc_code":{"type":"string","example":"T0345246801","description":"ISWC for the composition when available."},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"playback_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri","description":"Public URL returned for this resource or action."},"preview_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","format":"uri","description":"Public URL returned for this resource or action."},"documents_requested":{"type":"boolean","example":false,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."},"notes":{"type":"string","example":"Updated production notes for the delivery team.","description":"Operational notes visible to permitted organization users during review."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Track updated.","data":{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"title":"Midnight Atlas","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"},{"artist_id":"28636f32-61a4-41b8-8af4-70813049b9aa","name":"Olivia Smith","type":"Composer"}],"duration":196,"language":"English","primary_genre":"Electronic","secondary_genre":"Ambient","track_version":"Original Mix","isrc_code":"GBSMU2600001","iswc_code":"T0345246801","is_available_separately":true,"is_parental_advisory":false,"license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","playback_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","preview_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","documents_requested":false,"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00","notes":"Updated production notes for the delivery team."}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for isrc_code. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"isrc_code":["Enter a valid ISRC code or leave it blank when the platform should assign one."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"audio_file_id":{"type":"string","example":"audio_1783157400_6f9c2b8e4d1a","description":"Temporary audio upload reference returned by the upload endpoint."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"iswc_code":{"type":"string","example":"T-034.524.680-1","description":"ISWC for the composition when available."},"isrc_code":{"type":"string","example":"GB-SMU-26-00001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"lyrics":{"description":"Lyrics text when supplied for the track.","type":["string","null"]},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"notes":{"type":"string","example":"Updated production notes for the delivery team.","description":"Operational notes visible to permitted organization users during review."},"metadata":{"type":"object","additionalProperties":true,"properties":{"version":{"type":"string","example":"Original Mix","description":"version for metadata."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."}},"description":"Additional structured metadata for this resource."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"links":{"type":"array","items":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri"},"description":"External reference links for the track, such as preview, lyric, rights, or platform URLs relevant to catalog review."}},"required":["title"]},"example":{"title":"Midnight Atlas","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","primary_genre":"Electronic","iswc_code":"T-034.524.680-1","isrc_code":"GB-SMU-26-00001","lyrics":null,"is_available_separately":true,"is_parental_advisory":false,"license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","notes":"Updated production notes for release review.","metadata":{"version":"Original Mix","secondary_genre":"Ambient"},"duration":196,"links":["https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav"]}}}}},"delete":{"tags":["Tracks"],"summary":"Delete Track","operationId":"deleteTrack","description":"Delete Track. Use it to upload audio, maintain track metadata, manage contributor and rights information, attach documents, and assign tracks to visible releases. It removes, revokes, or cancels the target when permissions and resource state allow it, then returns a confirmation or policy error.","parameters":[{"name":"track_id","in":"path","required":true,"description":"Public track reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21"}],"responses":{"200":{"description":"Delete Track succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Track deleted successfully.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Track deleted successfully."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/tracks/{track_id}/assign/{release_id}":{"post":{"tags":["Tracks"],"summary":"Assign Track to Release","operationId":"assignTrackToRelease","description":"Attach a visible track to a visible release by track_id and release_id. Use this after creating both resources and before ordering or submitting the release.","parameters":[{"name":"track_id","in":"path","required":true,"description":"Public track reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21"},{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Assign Track to Release succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Track assigned to release.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"track_version":{"type":"string","example":"Original Mix","description":"Version label for the track, such as remix, radio edit, instrumental, or acoustic version."},"isrc_code":{"type":"string","example":"GBSMU2600001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"iswc_code":{"type":"string","example":"T0345246801","description":"ISWC for the composition when available."},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"playback_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri","description":"Public URL returned for this resource or action."},"preview_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","format":"uri","description":"Public URL returned for this resource or action."},"documents_requested":{"type":"boolean","example":false,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Track assigned to release.","data":{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"title":"Midnight Atlas","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"},{"artist_id":"28636f32-61a4-41b8-8af4-70813049b9aa","name":"Olivia Smith","type":"Composer"}],"duration":196,"language":"English","primary_genre":"Electronic","secondary_genre":"Ambient","track_version":"Original Mix","isrc_code":"GBSMU2600001","iswc_code":"T0345246801","is_available_separately":true,"is_parental_advisory":false,"license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","playback_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","preview_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","documents_requested":false,"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/tracks/{track_id}/document":{"post":{"tags":["Tracks"],"summary":"Submit Track Document","operationId":"submitTrackDocument","description":"Upload a supporting document for a track, such as copyright, license, or claim material. Send the file as multipart form data and keep the returned document reference for follow-up support.","parameters":[{"name":"track_id","in":"path","required":true,"description":"Public track reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21"}],"responses":{"200":{"description":"Submit Track Document succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Document submitted.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"document_id":{"type":"string","example":"a211d645-b1c8-43f7-8c7e-1b40adc2cc7c","format":"uuid","description":"Stable public document reference. Use this value in related endpoint paths and request bodies."},"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"submitted","description":"Current lifecycle status for this record."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Document submitted.","data":{"document_id":"a211d645-b1c8-43f7-8c7e-1b40adc2cc7c","track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","status":"submitted"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for document. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"document":["The document field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Multipart request payload.","content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":true,"properties":{"document":{"type":"string","description":"Binary file upload for this endpoint.","format":"binary"},"notes":{"type":"string","example":"License agreement for the vocal sample.","description":"Operational notes visible to permitted organization users during review."}},"required":["document"]},"example":{"document":"rights-declaration.pdf","notes":"License agreement for the vocal sample."}}}}}},"/api/v1/tracks/{track_id}/unassign/{release_id}":{"post":{"tags":["Tracks"],"summary":"Remove Track from Release","operationId":"removeTrackFromRelease","description":"Detach a track from a release by track_id and release_id when the release state allows catalog edits. The track remains available for other permitted workflows.","parameters":[{"name":"track_id","in":"path","required":true,"description":"Public track reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21"},{"name":"release_id","in":"path","required":true,"description":"Public release reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8"}],"responses":{"200":{"description":"Remove Track from Release succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Track removed from release.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"Track removed from release."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/tracks/upload":{"post":{"tags":["Tracks"],"summary":"Upload Track Audio","operationId":"uploadTrackAudio","description":"Upload a complete audio file and receive an audio_file_id. Use that reference when creating or replacing a track, and reserve track_id for the stable track created later.","parameters":[{"$ref":"#/components/parameters/ActingUser"}],"responses":{"200":{"description":"Upload Track Audio succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","const":true},"audio_file_id":{"type":"string","example":"audio_1783157400_6f9c2b8e4d1a","description":"Temporary audio upload reference returned by the upload endpoint."},"file_name":{"type":"string","example":"midnight-atlas.wav","description":"Stored file name for the uploaded audio."},"original":{"type":"string","example":"midnight-atlas-master.wav","description":"Original client-provided file name."},"links":{"type":"array","items":{"type":"string","format":"uri"},"description":"Audio delivery URLs prepared for the uploaded file."},"extensions":{"type":"object","additionalProperties":false,"required":["input","output"],"properties":{"input":{"type":"string","description":"Original audio format detected during upload."},"output":{"type":"string","description":"Playback or storage format prepared by the media pipeline."}}},"duration":{"type":["integer","null"],"minimum":0},"mime_type":{"type":["string","null"]},"checksum":{"type":["string","null"]}},"required":["success","audio_file_id","file_name","original","links","extensions","duration","mime_type","checksum"]},"example":{"success":true,"audio_file_id":"audio_1783157400_6f9c2b8e4d1a","file_name":"midnight-atlas.wav","original":"midnight-atlas-master.wav","links":["https://enterprise.spacemedia.uk/tracks/audio/midnight-atlas.wav"],"extensions":{"input":"wav","output":"wav"},"duration":196,"mime_type":"audio/wav","checksum":"sha256:7b89f8534f43e7c584fe5d8ac06d543750c501de39b2b1e2667010efc0f80a0e"}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for track. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"track":["Choose a valid audio file or track reference."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Multipart request payload.","content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":true,"properties":{"track":{"type":"string","description":"Binary file upload for this endpoint.","format":"binary"}},"required":["track"]},"example":{"track":"midnight-atlas-master.wav"}}}}}},"/api/v1/tracks/upload/chunk":{"post":{"tags":["Tracks"],"summary":"Upload Track Audio Chunk","operationId":"uploadTrackAudioChunk","description":"Upload one chunk of a larger audio file using a stable upload_session_id, chunk_index, and total_chunks. After all chunks are accepted, use the returned audio_file_id in track metadata calls.","parameters":[{"$ref":"#/components/parameters/ActingUser"}],"responses":{"200":{"description":"Upload Track Audio Chunk succeeded and returns the documented response body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackUploadStatus"},"example":{"success":true,"upload_session_id":"upload_midnight_atlas_20260704","received_chunks":[0,1,2,3],"total_chunks":8,"complete":false,"state":"receiving","expires_at":"2026-07-04T10:15:00+00:00","message":"Chunk uploaded successfully"}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for the chunk metadata or uploaded file. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"upload_session_id":["The upload session id field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Multipart request payload.","content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":true,"properties":{"upload_session_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$","example":"upload_midnight_atlas_20260704","description":"Stable client-generated upload session reference. Reuse it for every chunk and status check."},"chunk_index":{"type":"integer","example":3,"description":"Zero-based sequence number for this uploaded chunk within the upload session. The first chunk is 0."},"total_chunks":{"type":"integer","minimum":1,"maximum":64,"example":8,"description":"Total number of chunks expected for the upload session."},"file_name":{"type":"string","maxLength":255,"example":"midnight-atlas-master.wav","description":"Original audio file name, including a supported extension."},"file_size":{"type":"integer","minimum":1,"maximum":524288000,"example":83886080,"description":"Total size of the complete audio file in bytes."},"chunk":{"type":"string","description":"Binary chunk for a multipart audio upload session.","format":"binary"}},"required":["chunk_index","total_chunks","file_name","file_size","chunk"]},"example":{"upload_session_id":"upload_midnight_atlas_20260704","chunk_index":3,"total_chunks":8,"file_name":"midnight-atlas-master.wav","file_size":83886080,"chunk":"midnight-atlas-master.part001"}}}}}},"/api/v1/tracks/upload/{upload_session_id}":{"get":{"tags":["Tracks"],"summary":"Get Track Upload Status","operationId":"getTrackUploadStatus","description":"Recover the current state of a chunked audio upload after a retry, timeout, or lost final response. The result is scoped to the authenticated user and organization.","parameters":[{"$ref":"#/components/parameters/ActingUser"},{"name":"upload_session_id","in":"path","required":true,"description":"The upload_session_id originally sent with the chunked upload.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$"}}],"responses":{"200":{"description":"The upload session exists and its current state is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackUploadStatus"},"example":{"success":true,"complete":false,"upload_session_id":"upload_midnight_atlas_20260704","state":"receiving","received_chunks":[0,1,2,3],"total_chunks":8,"expires_at":"2026-07-04T10:15:00+00:00"}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"No active or recently completed upload session exists for this user and organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The upload session reference is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/upgrade":{"get":{"tags":["Plans and Upgrades"],"summary":"View Upgrade Options","operationId":"getUpgradeOptions","description":"Return plan and upgrade options available to the organization. Use this before creating a subscription checkout or presenting paid plan choices.","parameters":[],"responses":{"200":{"description":"View Upgrade Options succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"can_upgrade":{"type":"boolean","example":true,"description":"Whether the organization can move to the related package or plan."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"currency_symbol":{"type":"string","example":"GBP","description":"Currency symbol displayed with monetary amounts, such as £ or €."},"current_subscription":{"type":"object","additionalProperties":true,"properties":{"subscription_id":{"type":"string","example":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","format":"uuid","description":"Stable public subscription reference. Use this value in related endpoint paths and request bodies."},"status":{"type":"string","example":"active","description":"Current lifecycle status for this record."},"is_active":{"type":"boolean","example":true,"description":"is active for current_subscription."},"package":{"type":"object","additionalProperties":true,"properties":{"package_id":{"type":"string","example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","format":"uuid","description":"Stable public package reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Growth Distribution Monthly","description":"Display name for this package."},"type":{"type":"string","example":"membership","description":"Public type or role value for this item."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"price":{"type":"integer","example":49,"description":"price for package."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"royalty_percentage":{"type":"integer","example":85,"description":"royalty percentage for package."},"artist_profile_limit":{"type":"integer","example":25,"description":"artist profile limit for package."},"release_limit":{"type":"integer","example":50,"description":"release limit for package."},"release_limit_cycle":{"type":"string","example":"monthly","description":"release limit cycle for package."},"feature_list":{"type":"array","items":{"type":"string","example":"Unlimited team members"},"description":"feature list for package."}},"description":"package for current_subscription."},"subscribed_at":{"type":"string","example":"2026-06-01T09:00:00+00:00","format":"date-time","description":"Timestamp for when subscribed occurred, formatted as ISO 8601 when available."},"next_payment":{"type":"string","example":"2026-08-01T09:00:00+00:00","format":"date-time","description":"next payment for current_subscription."},"amount":{"type":"integer","example":49,"description":"Monetary amount in the currency shown on the same object."},"total_paid_amount":{"type":"integer","example":98,"description":"Monetary amount in the currency shown on the same object."},"gateway":{"type":"string","example":"stripe","description":"Payment gateway used for this checkout or billing flow.","enum":["airwallex","stripe","paypal"]}},"description":"Subscription currently active for the organization."},"packages":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"package_id":{"type":"string","example":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","format":"uuid","description":"Stable public package reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Growth Distribution Monthly","description":"Display name for this packages."},"type":{"type":"string","example":"membership","description":"Public type or role value for this item."},"status":{"type":"string","example":"published","description":"Current lifecycle status for this record."},"price":{"type":"integer","example":49,"description":"price for packages."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"royalty_percentage":{"type":"integer","example":85,"description":"royalty percentage for packages."},"artist_profile_limit":{"type":"integer","example":25,"description":"artist profile limit for packages."},"release_limit":{"type":"integer","example":50,"description":"release limit for packages."},"release_limit_cycle":{"type":"string","example":"monthly","description":"release limit cycle for packages."},"feature_list":{"type":"array","items":{"type":"string","example":"Unlimited team members"},"description":"feature list for packages."}}},"description":"Membership packages available to the organization."},"pay_per_release_plans":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"plan_id":{"type":"string","example":"d93dfb89-27ef-4104-a609-4e6dbd272c37","format":"uuid","description":"Stable public plan reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Single Release Credit","description":"Display name for this pay_per_release_plans."},"release_type":{"type":"string","example":"single","description":"release type for pay_per_release_plans."},"active":{"type":"boolean","example":true,"description":"active for pay_per_release_plans."},"price":{"type":"integer","example":9,"description":"price for pay_per_release_plans."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."},"royalty_percentage":{"type":"integer","example":90,"description":"royalty percentage for pay_per_release_plans."},"feature_list":{"type":"array","items":{"type":"string","example":"One single release"},"description":"feature list for pay_per_release_plans."}}},"description":"Pay-per-release plans available to the organization."},"available_gateways":{"type":"object","additionalProperties":true,"properties":{"stripe":{"type":"boolean","example":true,"description":"Whether stripe checkout is available for this organization."},"paypal":{"type":"boolean","example":true,"description":"Whether paypal checkout is available for this organization."},"airwallex":{"type":"boolean","example":true,"description":"Whether airwallex checkout is available for this organization."}},"description":"Saved payment methods visible to the organization for billing and checkout recovery."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"can_upgrade":true,"currency":"GBP","currency_symbol":"£","current_subscription":{"subscription_id":"ad3095e4-4628-43d0-8e47-d8996c7daf0d","status":"active","is_active":true,"package":{"package_id":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","name":"Growth Distribution Monthly","type":"membership","status":"published","price":49,"currency":"GBP","royalty_percentage":85,"artist_profile_limit":25,"release_limit":50,"release_limit_cycle":"monthly","feature_list":["Unlimited team members","Priority delivery review","Advanced catalog reporting"]},"subscribed_at":"2026-06-01T09:00:00+00:00","next_payment":"2026-08-01T09:00:00+00:00","amount":49,"total_paid_amount":98,"gateway":"stripe"},"packages":[{"package_id":"f3e184c8-8b3a-45b8-9bcb-cc12f70826b6","name":"Growth Distribution Monthly","type":"membership","status":"published","price":49,"currency":"GBP","royalty_percentage":85,"artist_profile_limit":25,"release_limit":50,"release_limit_cycle":"monthly","feature_list":["Unlimited team members","Priority delivery review","Advanced catalog reporting"]}],"pay_per_release_plans":[{"plan_id":"d93dfb89-27ef-4104-a609-4e6dbd272c37","name":"Single Release Credit","release_type":"single","active":true,"price":9,"currency":"GBP","royalty_percentage":90,"feature_list":["One single release","Standard delivery review"]}],"available_gateways":{"stripe":true,"paypal":true,"airwallex":true}}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/users":{"get":{"tags":["Users"],"summary":"List Users","operationId":"listUsers","description":"List organization users with public user_id and role_id values. Use this endpoint before assigning catalog ownership, checking user access, or selecting an acted-for user for permitted API work.","parameters":[{"name":"search","in":"query","required":false,"description":"Search term for matching visible records.","schema":{"type":"string","example":"midnight"},"example":"midnight"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20},{"name":"sort","in":"query","required":false,"description":"Sort direction for creation date.","schema":{"type":"string","example":"desc"},"example":"desc"}],"responses":{"200":{"description":"List Users succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this data."},"full_name":{"type":"string","example":"Maya Chen","description":"Full display name assembled from the account profile fields."},"first_name":{"type":"string","example":"Maya","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Chen","description":"Family name for the user or member profile."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"phone":{"type":"string","example":"+442071838750","description":"Phone number on the account profile when provided."},"language":{"type":"string","example":"en","description":"Primary language value used for profile, release, or track metadata."},"country":{"type":"string","example":"United Kingdom","description":"Country associated with the user, artist, or organization record."},"profile_photo":{"type":"string","example":"https://assets.spacemedia-docs.invalid/users/maya-chen/profile-photo.webp","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"verified":{"type":"boolean","example":true,"description":"Whether the account email or identity state is verified."},"email_verified_at":{"type":"string","example":"2026-06-25T08:15:00+00:00","format":"date-time","description":"Timestamp for when email verified occurred, formatted as ISO 8601 when available."},"last_login_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last login occurred, formatted as ISO 8601 when available."},"invitation_status":{"type":"string","example":"accepted","description":"Invitation lifecycle status, such as pending or accepted."},"is_invited":{"type":"boolean","example":false,"description":"Whether this user was created through an organization invitation."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this roles."}}},"description":"Roles assigned to the user or member within the organization."},"organization_name":{"type":"string","example":"Northstar Distribution","description":"Display name of the organization that owns the record."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","full_name":"Maya Chen","first_name":"Maya","last_name":"Chen","email":"maya.chen@northstar-distribution.co.uk","phone":"+442071838750","language":"en","country":"United Kingdom","profile_photo":"https://assets.spacemedia-docs.invalid/users/maya-chen/profile-photo.webp","verified":true,"email_verified_at":"2026-06-25T08:15:00+00:00","last_login_at":"2026-07-04T10:15:00+00:00","invitation_status":"accepted","is_invited":false,"is_suspended":false,"roles":[{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"}],"organization_name":"Northstar Distribution","created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for search. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"search":["The search field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Users"],"summary":"Create User","operationId":"createUser","description":"Create an organization user with name, email, public role references, and optional invite delivery. Use role_ids from the role list returned by the users or member role endpoints, never numeric role values.","parameters":[],"responses":{"201":{"description":"Create User created the resource and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"User invited.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"invitation_status":{"type":"string","example":"pending","description":"Invitation lifecycle status, such as pending or accepted."},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this roles."}}},"description":"Roles assigned to the user or member within the organization."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"User invited.","data":{"user_id":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","email":"eli.brooks@northstar-distribution.co.uk","invitation_status":"pending","roles":[{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"}]}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"422":{"description":"Validation failed for first_name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"first_name":["The first name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"first_name":{"type":"string","example":"Eli","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Brooks","description":"Family name for the user or member profile."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"role_ids":{"type":"array","items":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid"},"description":"Public role references assigned to the user. Use values returned by role or member role endpoints, not numeric role values."}},"required":["email","role_ids"]},"example":{"first_name":"Eli","last_name":"Brooks","email":"eli.brooks@northstar-distribution.co.uk","role_ids":["c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e"]}}}}}},"/api/v1/users/{user_id}":{"post":{"tags":["Users"],"summary":"Update User","operationId":"updateUser","description":"Update an organization user profile or role assignment by user_id. Submit only public role_ids and profile fields that the acted-for user is allowed to change for that account.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"}],"responses":{"200":{"description":"Update User succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"User updated successfully.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"User updated successfully."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for first_name. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"first_name":["The first name field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Request payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"first_name":{"type":"string","example":"Eli","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Brooks","description":"Family name for the user or member profile."},"role_ids":{"type":"array","items":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid"},"description":"Public role references assigned to the user. Use values returned by role or member role endpoints, not numeric role values."},"country":{"type":"string","example":"United Kingdom","description":"Country associated with the user, artist, or organization record."},"language":{"type":"string","example":"en","description":"Primary language value used for profile, release, or track metadata."}},"required":["first_name","last_name","role_ids"]},"example":{"first_name":"Eli","last_name":"Brooks","role_ids":["c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e"],"country":"United Kingdom","language":"en"}}}}}},"/api/v1/users/{user_id}/artists":{"get":{"tags":["Users"],"summary":"List User Artists","operationId":"listUserArtists","description":"List artist profiles associated with a user inside the organization. Use the returned artist_id values when filtering catalog work or assigning credits.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List User Artists succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Stable public artist reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this data."},"artist_type":{"type":"string","example":"Primary Artist","description":"Artist classification used for DSP metadata and credit display."},"spotify_id":{"type":"string","example":"3mY7kJqR8B2nQvP6LxT4Za","description":"Optional external Spotify artist reference for matching catalog profiles. It is not a SpaceMedia API path reference; use artist_id for SpaceMedia API calls."},"bio":{"type":"string","example":"Electronic artist and producer from London.","description":"Artist biography or descriptive profile text."},"country":{"type":"string","example":"GB","description":"Country associated with the user, artist, or organization record."},"releases_count":{"type":"integer","example":2,"description":"Number of releases currently associated with the artist."},"tracks_count":{"type":"integer","example":7,"description":"Number of tracks currently associated with the artist."},"total_streams":{"type":"integer","example":125000,"description":"Total reported streams when reporting data is available."},"created_at":{"type":"string","example":"2026-06-01T11:00:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","artist_type":"Primary Artist","spotify_id":"3mY7kJqR8B2nQvP6LxT4Za","bio":"Electronic artist and producer from London.","country":"GB","releases_count":2,"tracks_count":7,"total_streams":125000,"created_at":"2026-06-01T11:00:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/users/{user_id}/detail":{"get":{"tags":["Users"],"summary":"Get Organization User","operationId":"getOrganizationUser","description":"Return one organization user profile, assigned roles, account state, and the organization display name by user_id. The response never exposes organization identifiers because authentication already scopes the organization.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"}],"responses":{"200":{"description":"Get Organization User succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this data."},"full_name":{"type":"string","example":"Maya Chen","description":"Full display name assembled from the account profile fields."},"first_name":{"type":"string","example":"Maya","description":"Given name for the user or member profile."},"last_name":{"type":"string","example":"Chen","description":"Family name for the user or member profile."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."},"phone":{"type":"string","example":"+442071838750","description":"Phone number on the account profile when provided."},"language":{"type":"string","example":"en","description":"Primary language value used for profile, release, or track metadata."},"country":{"type":"string","example":"United Kingdom","description":"Country associated with the user, artist, or organization record."},"profile_photo":{"type":"string","example":"https://assets.spacemedia-docs.invalid/users/maya-chen/profile-photo.webp","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"verified":{"type":"boolean","example":true,"description":"Whether the account email or identity state is verified."},"email_verified_at":{"type":"string","example":"2026-06-25T08:15:00+00:00","format":"date-time","description":"Timestamp for when email verified occurred, formatted as ISO 8601 when available."},"last_login_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when last login occurred, formatted as ISO 8601 when available."},"invitation_status":{"type":"string","example":"accepted","description":"Invitation lifecycle status, such as pending or accepted."},"is_invited":{"type":"boolean","example":false,"description":"Whether this user was created through an organization invitation."},"is_suspended":{"type":"boolean","example":false,"description":"Whether organization access is currently suspended for this account."},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"role_id":{"type":"string","example":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","format":"uuid","description":"Stable public role reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Catalog Manager","description":"Display name for this roles."}}},"description":"Roles assigned to the user or member within the organization."},"organization_name":{"type":"string","example":"Northstar Distribution","description":"Display name of the organization that owns the record."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","data"]},"example":{"success":true,"data":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","full_name":"Maya Chen","first_name":"Maya","last_name":"Chen","email":"maya.chen@northstar-distribution.co.uk","phone":"+442071838750","language":"en","country":"United Kingdom","profile_photo":"https://assets.spacemedia-docs.invalid/users/maya-chen/profile-photo.webp","verified":true,"email_verified_at":"2026-06-25T08:15:00+00:00","last_login_at":"2026-07-04T10:15:00+00:00","invitation_status":"accepted","is_invited":false,"is_suspended":false,"roles":[{"role_id":"c0f1c68c-7c2f-4954-b52c-9d7e5eb46d3e","name":"Catalog Manager"}],"organization_name":"Northstar Distribution","created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/users/{user_id}/profile-photo":{"post":{"tags":["Users"],"summary":"Update User Profile Photo","operationId":"updateUserProfilePhoto","description":"Upload a replacement profile photo for an organization user by user_id. Send the image as multipart form data and use the returned user profile for subsequent display or audit purposes.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"}],"responses":{"200":{"description":"Update User Profile Photo succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"Profile photo updated successfully.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."},"data":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"profile_photo":{"type":"string","example":"https://assets.spacemedia-docs.invalid/users/eli-brooks/profile-photo.webp","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}},"description":"Primary response payload for this request."}},"required":["success","message","data"]},"example":{"success":true,"message":"Profile photo updated successfully.","data":{"user_id":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","profile_photo":"https://assets.spacemedia-docs.invalid/users/eli-brooks/profile-photo.webp","updated_at":"2026-07-04T10:15:00+00:00"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for profile_photo. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"profile_photo":["The profile photo field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"description":"Multipart request payload.","content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"properties":{"profile_photo":{"type":"string","description":"Binary profile image file for the user account.","format":"binary"}},"required":["profile_photo"]},"example":{"profile_photo":"eli-brooks-profile.webp"}}}}}},"/api/v1/users/{user_id}/releases":{"get":{"tags":["Users"],"summary":"List User Releases","operationId":"listUserReleases","description":"List releases associated with a user inside the organization. Use the returned release_id values for track, rights, review, and checkout follow-up calls.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List User Releases succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."},"format":{"type":"string","example":"single","description":"Release format, such as single, EP, or album."},"label":{"type":"string","example":"Night Shift Records","description":"Label name attached to the release metadata."},"genre":{"type":"string","example":"Electronic","description":"Primary release or track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"explicit_content":{"type":"boolean","example":false,"description":"Whether the release or track is marked as explicit."},"upc_code":{"type":"string","example":"5054429191012","description":"UPC assigned to the release, or null when it has not been assigned yet."},"reference_number":{"type":"string","example":"NSD-2026-041","description":"Human-readable catalog or billing reference shown in the dashboard."},"scheduled_date":{"type":"string","example":"2026-08-21","format":"date","description":"Scheduled release date used for delivery planning and catalog display."},"original_release_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for original release."},"copyright_detection_enabled":{"type":"boolean","example":true,"description":"Whether copyright checking is enabled for the organization or release workflow."},"price_category":{"type":"string","example":"mid","description":"Release price tier or commercial category used for store delivery and billing decisions."},"territories":{"type":"array","items":{"type":"string","example":"GB"},"description":"Territory codes where the release or rights metadata should apply."},"distribution":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","example":"spotify","description":"Delivery channel or store identifier using public snake_case values."},"status":{"type":"string","example":"selected","description":"Current lifecycle status for this record."}}},"description":"Delivery destinations and their organization-visible status values."},"cover_art":{"type":"string","example":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","format":"uri","description":"Public media URL or asset reference for the uploaded image."},"track_count":{"type":"integer","example":1,"description":"Number of track records visible in this context."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"created_by":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this created_by."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User that created the record when available to the current organization."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft","format":"single","label":"Night Shift Records","genre":"Electronic","secondary_genre":"Ambient","language":"English","explicit_content":false,"upc_code":"5054429191012","reference_number":"NSD-2026-041","scheduled_date":"2026-08-21","original_release_date":"2026-08-21","copyright_detection_enabled":true,"price_category":"mid","territories":["GB","US","DE","NL"],"distribution":[{"channel":"spotify","status":"selected"},{"channel":"apple_music","status":"selected"},{"channel":"youtube_music","status":"selected"}],"cover_art":"https://assets.spacemedia-docs.invalid/releases/midnight-atlas/cover.jpg","track_count":1,"artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"}],"created_by":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/users/{user_id}/revenue":{"get":{"tags":["Users"],"summary":"List User Revenue","operationId":"listUserRevenue","description":"List revenue records visible for a user. The response uses release_id and track_id references so clients can connect revenue back to catalog metadata.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List User Revenue succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"revenue_record_id":{"type":"string","example":"rev_midnight_atlas_june_2026","description":"Stable public revenue record reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"track":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."}},"description":"Track summary connected to the release, split, document, or revenue item."},"store":{"type":"string","example":"Spotify","description":"DSP, storefront, or destination where the release, track, or smartlink is available."},"country":{"type":"string","example":"GB","description":"Country associated with the user, artist, or organization record."},"month":{"type":"string","example":"2026-06","description":"Calendar month represented by the reporting or revenue entry."},"revenue":{"type":"number","example":128.42,"description":"Revenue amount, trend, or summary visible to the organization."},"currency":{"type":"string","example":"GBP","description":"ISO currency code for the amount shown on the same object."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"revenue_record_id":"rev_midnight_atlas_june_2026","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"track":{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","title":"Midnight Atlas"},"store":"Spotify","country":"GB","month":"2026-06","revenue":128.42,"currency":"GBP"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/users/{user_id}/splits":{"get":{"tags":["Users"],"summary":"List User Revenue Splits","operationId":"listUserSplits","description":"List revenue splits where the user is creator or beneficiary. Use split_id values to inspect, update, or confirm split participation.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List User Revenue Splits succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"split_id":{"type":"string","example":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","format":"uuid","description":"Stable public split reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas Producer Share","description":"Catalog or content title shown in the dashboard and API responses."},"percentage":{"type":"integer","example":25,"description":"Revenue split percentage assigned to this beneficiary."},"start_date":{"type":"string","example":"2026-08-21","format":"date","description":"Calendar date for start."},"end_date":{"description":"Calendar date for end.","type":["string","null"],"format":"date"},"locked":{"type":"boolean","example":false,"description":"Whether the split, role, or configuration is locked from further editing in its current state."},"beneficiary":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Eli Brooks","description":"Display name for this beneficiary."},"email":{"type":"string","example":"eli.brooks@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User or collaborator receiving the revenue split share."},"creator":{"type":"object","additionalProperties":true,"properties":{"user_id":{"type":"string","example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","format":"uuid","description":"Stable public user reference. Use this value in related endpoint paths and request bodies."},"name":{"type":"string","example":"Maya Chen","description":"Display name for this creator."},"email":{"type":"string","example":"maya.chen@northstar-distribution.co.uk","description":"Email address associated with the account, member, invitation, or beneficiary."}},"description":"User summary for the person who created the record."},"releases":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}}},"description":"Releases visible for the current organization and permission scope."},"tracks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."}}},"description":"Tracks included in the release or returned by the catalog query."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"split_id":"8df80f4e-63df-4562-87e8-f1b2f2f0ce47","title":"Midnight Atlas Producer Share","percentage":25,"start_date":"2026-08-21","end_date":null,"locked":false,"beneficiary":{"user_id":"43cda1b2-f7e9-49c7-b4fb-4fcfc5a02a9c","name":"Eli Brooks","email":"eli.brooks@northstar-distribution.co.uk"},"creator":{"user_id":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71","name":"Maya Chen","email":"maya.chen@northstar-distribution.co.uk"},"releases":[{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"}],"tracks":[{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","title":"Midnight Atlas"}]}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/users/{user_id}/suspend":{"post":{"tags":["Users"],"summary":"Suspend User","operationId":"suspendUser","description":"Suspend an organization user by user_id when policy allows it. Use this to block future access without deleting catalog ownership or historical activity records.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"}],"responses":{"200":{"description":"Suspend User succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"User suspended.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"User suspended."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/users/{user_id}/tracks":{"get":{"tags":["Users"],"summary":"List User Tracks","operationId":"listUserTracks","description":"List tracks associated with a user inside the organization. Use the returned track_id values for metadata edits, document uploads, and release assignment calls.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"},{"name":"page","in":"query","required":false,"description":"Page number to return.","schema":{"type":"integer","example":1},"example":1},{"name":"size","in":"query","required":false,"description":"Number of records per page.","schema":{"type":"integer","example":20},"example":20}],"responses":{"200":{"description":"List User Tracks succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"track_id":{"type":"string","example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","format":"uuid","description":"Stable public track reference. Use this value in related endpoint paths and request bodies."},"release":{"type":"object","additionalProperties":true,"properties":{"release_id":{"type":"string","example":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","format":"uuid","description":"Stable public release reference. Use this value in related endpoint paths and request bodies."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"status":{"type":"string","example":"draft","description":"Current lifecycle status for this record."}},"description":"Release summary or nested release object connected to this workflow."},"title":{"type":"string","example":"Midnight Atlas","description":"Catalog or content title shown in the dashboard and API responses."},"artists":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"artist_id":{"type":"string","example":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","format":"uuid","description":"Public artist reference returned by the artists API."},"name":{"type":"string","example":"Nova Vale","description":"Display name for this artists."},"type":{"type":"string","example":"Primary Artist","description":"Artist credit role for this release or track, such as Primary Artist or Featured Artist."}},"required":["artist_id","type"]},"description":"Artists credited or attached to this catalog record."},"duration":{"type":"integer","example":196,"description":"Track duration in seconds or a display-ready duration value."},"language":{"type":"string","example":"English","description":"Primary language value used for profile, release, or track metadata."},"primary_genre":{"type":"string","example":"Electronic","description":"Primary track genre selected from supported values."},"secondary_genre":{"type":"string","example":"Ambient","description":"Optional secondary genre used for more precise metadata."},"track_version":{"type":"string","example":"Original Mix","description":"Version label for the track, such as remix, radio edit, instrumental, or acoustic version."},"isrc_code":{"type":"string","example":"GBSMU2600001","description":"ISRC assigned to the track, or blank when one should be assigned later."},"iswc_code":{"type":"string","example":"T0345246801","description":"ISWC for the composition when available."},"is_available_separately":{"type":"boolean","example":true,"description":"Whether the track can be distributed or sold separately from the release when supported by selected stores."},"is_parental_advisory":{"type":"boolean","example":false,"description":"Whether the track should be marked with an explicit or parental advisory flag."},"license_holder_year":{"type":"integer","example":2026,"description":"Year associated with the rights holder for the release or track metadata."},"license_holder_name":{"type":"string","example":"Night Shift Records Ltd","description":"Legal name of the person or company that holds the relevant rights for the release or track."},"playback_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","format":"uri","description":"Public URL returned for this resource or action."},"preview_url":{"type":"string","example":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","format":"uri","description":"Public URL returned for this resource or action."},"documents_requested":{"type":"boolean","example":false,"description":"Whether the track currently requires supporting rights or copyright documentation before review can continue."},"created_at":{"type":"string","example":"2026-07-04T09:30:00+00:00","format":"date-time","description":"Timestamp for when created occurred, formatted as ISO 8601 when available."},"updated_at":{"type":"string","example":"2026-07-04T10:15:00+00:00","format":"date-time","description":"Timestamp for when updated occurred, formatted as ISO 8601 when available."}}},"description":"Primary response payload for this request."},"meta":{"type":"object","additionalProperties":true,"properties":{"current_page":{"type":"integer","example":1,"description":"current page for meta."},"last_page":{"type":"integer","example":1,"description":"last page for meta."},"per_page":{"type":"integer","example":20,"description":"per page for meta."},"total":{"type":"integer","example":1,"description":"Total number of records matching the current filters."},"from":{"type":"integer","example":1,"description":"from for meta."},"to":{"type":"integer","example":1,"description":"to for meta."}},"description":"Pagination, filter, or response metadata for this request."}},"required":["success","data","meta"]},"example":{"success":true,"data":[{"track_id":"e454b6f8-df5b-49db-9b9f-916f74ec1f21","release":{"release_id":"b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8","title":"Midnight Atlas","status":"draft"},"title":"Midnight Atlas","artists":[{"artist_id":"6f209ac7-d82c-4c8f-9d3e-bfe39c0df802","name":"Nova Vale","type":"Primary Artist"},{"artist_id":"28636f32-61a4-41b8-8af4-70813049b9aa","name":"Olivia Smith","type":"Composer"}],"duration":196,"language":"English","primary_genre":"Electronic","secondary_genre":"Ambient","track_version":"Original Mix","isrc_code":"GBSMU2600001","iswc_code":"T0345246801","is_available_separately":true,"is_parental_advisory":false,"license_holder_year":2026,"license_holder_name":"Night Shift Records Ltd","playback_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/master.wav","preview_url":"https://media.spacemedia-docs.invalid/audio/midnight-atlas/preview.mp3","documents_requested":false,"created_at":"2026-07-04T09:30:00+00:00","updated_at":"2026-07-04T10:15:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"422":{"description":"Validation failed for page. The request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Validation failed.","errors":{"page":["The page field is invalid for this request."]}}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/users/{user_id}/unsuspend":{"post":{"tags":["Users"],"summary":"Unsuspend User","operationId":"unsuspendUser","description":"Restore access for a suspended organization user by user_id. The response confirms the active account state and can be followed by a user detail lookup.","parameters":[{"name":"user_id","in":"path","required":true,"description":"Public user reference returned by the API.","schema":{"type":"string","format":"uuid"},"example":"7d2d9f72-c0a2-4d4b-9b6d-7caa942b8a71"}],"responses":{"200":{"description":"Unsuspend User succeeded and returns the documented response body.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"User unsuspended.","description":"Human-readable outcome or error message suitable for logs and operator interfaces."}},"required":["success","message"]},"example":{"success":true,"message":"User unsuspended."}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"The requested resource was not found in the authenticated organization."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/tracks/{track_id}/document/download":{"get":{"tags":["Tracks"],"summary":"Download Track Document","operationId":"downloadTrackDocument","description":"Generate a temporary download URL for the supporting document attached to a visible track. The track must belong to the organization and the caller must be allowed to view it.","parameters":[{"name":"track_id","in":"path","required":true,"description":"Public track reference returned by track list, create, or release track endpoints.","schema":{"type":"string","format":"uuid"},"example":"e454b6f8-df5b-49db-9b9f-916f74ec1f21"}],"responses":{"200":{"description":"Download URL created.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","example":true,"description":"Whether the API request completed successfully."},"message":{"type":"string","example":"File download link generated successfully.","description":"Human-readable outcome suitable for logs and operator interfaces."},"document_url":{"type":"string","format":"uri","example":"https://assets.spacemedia-docs.invalid/documents/midnight-atlas/rights-declaration.pdf","description":"Temporary or public URL where the document can be downloaded."}},"required":["success","message"]},"example":{"success":true,"message":"File download link generated successfully.","document_url":"https://assets.spacemedia-docs.invalid/documents/midnight-atlas/rights-declaration.pdf"}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Authentication token is missing or invalid."}}}},"403":{"description":"Permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"You do not have permission to perform this action."}}}},"404":{"description":"Track or document not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Document not found."}}}},"429":{"description":"Rate limit reached. Retry after the client has slowed down.","headers":{"Retry-After":{"description":"Seconds to wait before retrying when returned by the API.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"success":false,"message":"Too many requests. Please retry after a short delay."}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}