API REFERENCE

Create Catalog

On this page

POST/api/catalogs

Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via Get Catalogs. When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/catalogs' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "snapshot": "YOUR_ID",
  "organization_id": "YOUR_ID"
}'

Request body required

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

application/json

namestring

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

snapshotstring

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.

format: uuid

organization_idstring

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.

format: uuid

Responses

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

application/json

statusstring · enum

Status of the request

Values: "success", "error"

catalogobject

A catalog with its metadata

Properties

idstring

Unique identifier for the catalog

format: uuid

namestring

Name of the catalog

created_atstring

ISO timestamp of when the catalog was created

format: date-time

updated_atstring

ISO timestamp of when the catalog was last updated

format: date-time

songs_addedinteger

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

errorstring

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

400Bad request - neither name nor snapshot provided, or invalid snapshot

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

401Unauthorized - missing or invalid credentials

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

403Forbidden - the snapshot belongs to a different account, or the caller is not a member of the organization named by organization_id

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

404Not found - no snapshot exists for the supplied snapshot

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download releases.json

View operation source

json

{
  "description": "Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Catalog to create. Provide name, snapshot, or both - at least one is required.",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateCatalogRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Catalog created, or the existing catalog returned when re-materializing the same snapshot (idempotent)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateCatalogResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - neither name nor snapshot provided, or invalid snapshot",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - the snapshot belongs to a different account, or the caller is not a member of the organization named by organization_id",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Not found - no snapshot exists for the supplied snapshot",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    }
  }
}