Skip to main content
POST
/
catalog-import
/
fetch
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"
}
'
{
  "status": "success",
  "message": "Metadata import job queued",
  "data": {
    "jobId": "<string>",
    "batchId": "metadata-import-8f14e45f-ceea-4d5e-8b3a-0a1b2c3d4e5f"
  }
}
This endpoint requires authentication. Include your Bearer token in the Authorization header.

​
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