Queue a metadata fetch + staging job

curl --request POST \ --url https://api.royalti.io/catalog-import/fetch \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "artistExternalId": "4kSvTBOm6QI0ivKlqZJfDe", "market": "US" } '

Description

POST /catalog-import/fetch

Description: Queues a background job (metadataImportQueue) that fetches metadata from every active provider for the given artist/ISRCs/UPCs, merges the results across providers with provenance tracking, and stages the outcome as CatalogImportItem rows for this tenant. This call never writes to Asset/Product directly — it only returns a jobId and batchId to poll and review.

Authorization:

Required role: admin or higher

Method: POST

Code Examples

const response = await fetch('https://api.royalti.io/catalog-import/fetch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "ref": "#/components/schemas/CatalogImportFetchRequest"
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
  'https://api.royalti.io/catalog-import/fetch',
  headers={
    'Authorization': f'Bearer {token}'
  },
  json={"ref":"#/components/schemas/CatalogImportFetchRequest"}
)

data = response.json()
print(data)

curl -X POST https://api.royalti.io/catalog-import/fetch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"#/components/schemas/CatalogImportFetchRequest"}'

Authorizations

Authorization

string

header

required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Body

application/json

At least one of artistExternalId, isrcs, or upcs is required. artistExternalId triggers a full artist-catalog walk on the primary catalog provider; every ISRC/UPC discovered during that walk is automatically queued for cross-provider enrichment lookups alongside any explicitly supplied isrcs/upcs.

artistExternalId

string

Provider-native artist id on the primary catalog provider, resolved via GET /search.

isrcs

string[]

ISRCs to fetch and merge. Capped at 500 per import.

Maximum array length: 500

Example:

["USRC17607839"]

upcs

string[]

UPCs/barcodes to fetch and merge. Capped at 500 per import.

Maximum array length: 500

Example:

["00602435054101"]

market

string

ISO country code — availability market passed to the primary catalog provider's artist-catalog walk.

Example:

"US"

Response

Import job queued

status

string

Example:

"success"

message

string

Example:

"Metadata import job queued"

data

object

Show child attributes

​Description

​Code Examples

Authorizations

Body

Response

Description

Code Examples