Catalogs and tenancy

A catalog is the boundary around your data. Understanding what sits inside it explains most of the API's shape.

Organizations and catalogs#

An organization is a //SCHEMA customer. It owns the people who sign in, the API keys, the SFTP endpoint and its delivery accounts.

A catalog is a body of music data that belongs to one organization: releases, tracks, parties, credits, deliveries. Most organizations have one; some keep a second for testing. The catalog is the isolation boundary — no query can see across it.

The catalog comes from the credential#

Look through the reference and you will not find an argument that selects a catalog. That is deliberate. An API key is issued for one catalog; a signed-in user works in the catalog they chose. Every operation acts on that catalog and nothing else.

The alternative — a catalogId argument checked against the caller's permissions — makes isolation depend on every single operation remembering to check. With the catalog taken from the credential, there is nothing to remember and nothing to get wrong: a request cannot even name someone else's catalog.

It also shapes how "not found" behaves. Asking for a UPC that exists in another catalog returns exactly what asking for a UPC that exists nowhere returns — null — so a key cannot be used to discover what other customers have.

Your data is yours#

Everything a label or you assert about music — releases, titles, credits, parties, labels, copyright notices — is stored per catalog. If two catalogs each receive the same album, each has its own copy of the metadata.

That can look wasteful, but the alternative is worse. With one shared record, one customer's corrections would change another customer's catalog, and a mistyped identifier in one delivery could attach data to someone else's release. Keeping assertions per catalog means your catalog changes only because of deliveries into it and edits you make.

Parties are per catalog too#

A party — an artist, a label — is scoped to the catalog, and within it the same party is reused across releases: the same label on forty releases is one partyPk. Parties with a DPID are matched by it; parties without one are never merged by name alone, because two different artists can share a name.