Skip to main content
POST
/
api
/
catalogs
cURL
curl --request POST \
  --url https://api.recoupable.com/api/catalogs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "snapshot": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "catalog": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "songs_added": 123,
  "error": "<string>"
}

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 owning account is taken from the request credentials, never from this body.

​
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.

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')