Skip to main content
POST
cURL

Authorizations

x-api-key
string
header
required

Your Recoup API key. Learn more.

Body

application/json

Catalog to create. Provide name, snapshot, or both - at least one is required.

Request body for creating a catalog. At least one of name or snapshot must be supplied. The catalog is owned by the authenticated account unless organization_id names an organization to own it instead.

name
string

Optional. Display name for the catalog. If omitted when snapshot is supplied, a name is derived from the source run.

snapshot
string<uuid>

Optional. ID of a completed playcount snapshot (valuation run) owned by the authenticated account. Its measured ISRCs are added to the new catalog as catalog songs. Create one with Create measurement job.

organization_id
string<uuid>

Optional. ID of an organization to own the catalog instead of the calling account. Every member of that organization then sees the catalog in their own Get Catalogs response, without passing the organization's id. The caller must be a member of the organization; otherwise the request is rejected with 403. Omit to own the catalog personally, which is the default.

Response

Catalog created, or the existing catalog returned when re-materializing the same snapshot (idempotent)

Response returned after creating, or idempotently re-fetching, a catalog

status
enum<string>

Status of the request

Available options:
success,
error
catalog
object

A catalog with its metadata

songs_added
integer

Number of catalog songs materialized from the source. 0 when no snapshot was supplied, or when the run was already materialized (idempotent re-claim).

error
string

Error message (only present if status is 'error')