Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Update Catalog Stream Tracking

On this page
POST/api/catalogs/{catalogId}/stream-tracking

Enable starts initial 62-day backfill and daily refresh at 09:00 UTC. Source window ends two UTC dates before the run date to allow reporting lag; source freshness is not guaranteed. New recordings join the next run. Maximum 250 recordings per catalog; larger catalogs fail before provider calls. Disable fences future writes and retains saved history. Refresh claims at most one run per UTC day and subscription revision; repeated enable is idempotent. If today was already claimed, collection.state=already_claimed_or_disabled and no duplicate provider work starts; failed claims can run again the next day. Failures are isolated by recording and exposed in coverage. Standard MCP manage_catalog_stream_tracking. Enabled tracking makes asynchronous provider calls. API-key/Privy bearer auth supported; identity overrides rejected. Requires API and database feature release. Unchanged daily values reuse their saved versions; new dates and corrections are appended, with fresh coverage/provenance receipts for every run.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/catalogs/YOUR_CATALOG_ID/stream-tracking' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "enable"
}'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/catalogs/{catalogId}/stream-tracking' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "enable"
}'

Parameters

Path parameters

catalogIdstringrequired

Catalog owned by the authenticated account or an organization it currently belongs to.

Request body required

application/json

actionstring · enumrequired

Values: "enable", "disable", "refresh"

Responses

200Tracking state and asynchronous collection receipt

application/json

statusstring
catalog_idstring

format: uuid

providerstring · enum

Values: "luminate"

platformstring · enum

Values: "all_dsps"

metricstring · enum

Values: "daily_streams"

latest_runobject | null

Run status, per-ISRC coverage, errors, window and completion timestamp.

Properties for latest_run
idstring

format: uuid

catalog_idstring

format: uuid

revisionstring

format: uuid

scheduled_daystring

format: date

sincestring

format: date

untilstring

format: date

statusstring · enum

Values: "queued", "running", "complete", "partial", "failed", "cancelled"

coverageobject
errorstring | null
created_atstring

format: date-time

finished_atstring | null

format: date-time

territorystring · enum

Values: "worldwide"

trackingobject | null
Properties for tracking
catalog_idstring

format: uuid

owner_idstring

format: uuid

enabledboolean
revisionstring

format: uuid

updated_atstring

format: date-time

collectionobject | null
Properties for collection
statestring · enum

Values: "started", "already_claimed_or_disabled"

run_idstring | null

format: uuid

workflow_run_idstring
400Invalid input

No response body schema is specified.

401Authentication required

No response body schema is specified.

404Catalog not accessible

No response body schema is specified.

409Tracking must be enabled before refresh

No response body schema is specified.

429Too many tracking control requests; limited to 10 per account per minute across REST and MCP.

No response body schema is specified.

503Storage, configuration or dispatch unavailable

No response body schema is specified.

Full specification

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

Download releases.json
View operation source
json
{
  "summary": "Control daily catalog tracking",
  "description": "Enable starts initial 62-day backfill and daily refresh at 09:00 UTC. Source window ends two UTC dates before the run date to allow reporting lag; source freshness is not guaranteed. New recordings join the next run. Maximum 250 recordings per catalog; larger catalogs fail before provider calls. Disable fences future writes and retains saved history. Refresh claims at most one run per UTC day and subscription revision; repeated enable is idempotent. If today was already claimed, collection.state=already_claimed_or_disabled and no duplicate provider work starts; failed claims can run again the next day. Failures are isolated by recording and exposed in coverage. Standard MCP manage_catalog_stream_tracking. Enabled tracking makes asynchronous provider calls. API-key/Privy bearer auth supported; identity overrides rejected. Requires API and database feature release. Unchanged daily values reuse their saved versions; new dates and corrections are appended, with fresh coverage/provenance receipts for every run.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "catalogId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Catalog owned by the authenticated account or an organization it currently belongs to."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "action"
          ],
          "additionalProperties": false,
          "properties": {
            "action": {
              "type": "string",
              "enum": [
                "enable",
                "disable",
                "refresh"
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Tracking state and asynchronous collection receipt",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "catalog_id": {
                "type": "string",
                "format": "uuid"
              },
              "provider": {
                "type": "string",
                "enum": [
                  "luminate"
                ]
              },
              "platform": {
                "type": "string",
                "enum": [
                  "all_dsps"
                ]
              },
              "metric": {
                "type": "string",
                "enum": [
                  "daily_streams"
                ]
              },
              "latest_run": {
                "$ref": "#/components/schemas/CatalogStreamRun",
                "description": "Run status, per-ISRC coverage, errors, window and completion timestamp."
              },
              "territory": {
                "type": "string",
                "enum": [
                  "worldwide"
                ]
              },
              "tracking": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "catalog_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "owner_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "revision": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "updated_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              },
              "collection": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "state": {
                    "type": "string",
                    "enum": [
                      "started",
                      "already_claimed_or_disabled"
                    ]
                  },
                  "run_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid"
                  },
                  "workflow_run_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "401": {
      "description": "Authentication required"
    },
    "404": {
      "description": "Catalog not accessible"
    },
    "409": {
      "description": "Tracking must be enabled before refresh"
    },
    "429": {
      "description": "Too many tracking control requests; limited to 10 per account per minute across REST and MCP."
    },
    "503": {
      "description": "Storage, configuration or dispatch unavailable"
    }
  }
}