How Reporting Works

The Reports API covers the operational lifecycle around royalty reporting: report intake, published analytics, exports, mapping and catalog review, reconciliation, anomalies, disputes, payout exceptions, and signed webhook ingress.

It runs on its own host, reports.spacemedia.uk, with its own credentials. Nothing carries over from the Delivery API.

Tenants

Everything here is scoped to a tenant: the reporting account your credentials belong to. Where the Delivery API says organization, the Reports API says tenant. They are the same idea, but issued separately, and one identifier never stands in for the other.

You send the tenant on every request as X-Tenant-ID. SpaceMedia gives you the value along with your client credentials. Because every token, import, export, and evidence record is bound to one tenant, a reference from one tenant is meaningless in another, and cross-tenant results must never share a cache.

The two access surfaces

This is the most important thing to understand before you write any code.

They are not interchangeable. Human review and approval operations stay outside machine authority on purpose, and no amount of scope on a machine client grants them. If an operation you need is only on the human surface, that is a deliberate control, not a gap to work around.

Integration principles

Preserve decimal precision. Keep amounts as strings or arbitrary-precision decimals. A float somewhere in your pipeline is a reconciliation failure waiting to be discovered months later.

Keep context attached to every value. Currency and reporting period travel with the amount. Storing a bare number loses the only things that make it comparable.

Use references exactly as returned. Public references are opaque. Do not parse, shorten, or regenerate them.

Do not infer authorization from a visible control. A dashboard button is not evidence that your machine client can perform the same action.

Reconcile against evidence resources. Completed imports and exports have documented evidence records. Use them rather than assuming success from a 200.

Treat flag and policy denials as unavailable capability. They are configuration states, not transient server failures, and retrying will not change the outcome.

Common questions

Can I use my Delivery API credentials here? No. The two APIs have separate credentials, hosts, scopes, and release cycles. Never reuse one against the other.

Why can I read an operation in the contract but not call it? The contract documents implemented behavior. Route publication and tenant approval are separate controls. See Availability.

How should I handle a response field I do not recognize? Ignore it safely. Compatible additions can introduce new optional fields and enum values at any time, and a strict parser will break on the next release.

Where are the exact request and response shapes? On each endpoint page, generated from the checked-in OpenAPI 3.1 contract. Start at machine authentication and select operations from the sidebar.