The Undercore API uses API keys passed in the X-API-Key HTTP header. Keys are tenant-scoped and scope-limited.

Header Format

X-API-Key: uc_live_<token>

Key Prefixes

Scopes

Each key is issued with a specific set of scopes. Requests that require a scope not granted to your key return 403 Forbidden.

Managing Keys

Keys are managed from the portal UI (Settings → API Keys) or via the management API:

# Requires portal session cookie (portal.undercore.pro)
curl -X POST https://api.undercore.pro/api/undercore/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name":"my-integration","scopes":["read:works","read:writers"],"expires_in_days":365}' \
  --cookie "pt_undercore=YOUR_SESSION"

Base URL: https://api.undercore.pro — All endpoints require an X-API-Key header.

Endpoints

Work Status Values

Works follow the CISAC lifecycle with 6 official status values:

Works represent musical compositions in your catalog. Each work has an optional ISWC, a lifecycle status, and a set of right holders with splits.

{
  "works": [
    {
      "id": 1,
      "title": "Midnight Serenade",
      "iswc": "T-000.000.001-0",
      "status": "registered",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-02-01T08:30:00Z"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 142
}

{
  "work": {
    "id": 1,
    "title": "Midnight Serenade",
    "iswc": "T-000.000.001-0",
    "status": "registered",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-02-01T08:30:00Z"
  }
}

Writers are the composers and lyricists registered in your catalog. Each writer has optional IPI and PRO affiliation fields.

{
  "writers": [
    {
      "id": 1,
      "name": "ALEX DEMO",
      "ipi": "00000000001",
      "pro_affiliation": "ASCAP",
      "created_at": "2026-01-10T09:00:00Z"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 3
}

Test the API with demo data instantly — no account needed. Sandbox keys are scoped to a demo tenant with fictitious publishing data and expire after 24 hours.

Generate a Sandbox Key

Click the button below to generate a uc_sandbox_ key instantly. No sign-up required.

Demo Data Available

The sandbox tenant contains the following fictitious publishing data for testing:

Works (5 demo entries)

Writers (3 demo entries)

Sandbox Status API

curl https://api.undercore.pro/api/undercore/sandbox/status

Official thin-wrapper SDKs for TypeScript/Node and Python. Zero config beyond your API key.

npm install @undercore/sdk

import { Undercore } from '@undercore/sdk';

const uc = new Undercore({
  apiKey: 'uc_live_...',
  // baseUrl: 'https://api.undercore.pro', // default
});

// List works (paginated)
const result = await uc.works.list({ page: 1, per_page: 50 });
console.log(result.works);     // Work[]
console.log(result.total);     // number

// Get single work
const { work } = await uc.works.get(42);
console.log(work.status);      // 'registered' | 'documented' | ...

// List writers
const writers = await uc.writers.list();

import { Undercore, UndercoreAPIError } from '@undercore/sdk';

try {
  const work = await uc.works.get(99999);
} catch (err) {
  if (err instanceof UndercoreAPIError) {
    console.log(err.status);   // 404
    console.log(err.detail);   // "Obra no encontrada"
  }
}

import { Work, Writer, WorksResponse } from '@undercore/sdk';

// Work.status is a discriminated union:
// 'draft' | 'needs_review' | 'documented' | 'registered' | 'conflict' | 'archived'

function isPublished(work: Work): boolean {
  return work.status === 'registered';
}

pip install undercore-sdk

from undercore import Undercore

# Context manager (recommended — auto-closes HTTP connection)
with Undercore(api_key="uc_live_...") as uc:

    # List works
    result = uc.works.list(page=1, per_page=50)
    for work in result.works:
        print(work.title, work.status)

    # Get single work
    work = uc.works.get(1)
    print(work.iswc)   # Optional[str]

    # List writers
    writers = uc.writers.list()
    print(writers.total)

from undercore import Undercore, UndercoreError

with Undercore(api_key="uc_live_...") as uc:
    try:
        work = uc.works.get(99999)
    except UndercoreError as e:
        print(e.status)   # 404
        print(e.detail)   # "Obra no encontrada"

from undercore.types import Work, Writer, WorksResponse

# Work.status is a Literal type:
# "draft" | "needs_review" | "documented" | "registered" | "conflict" | "archived"

def is_published(work: Work) -> bool:
    return work.status == "registered"

Rate limits are enforced per API key. When exceeded, the API returns 429 Too Many Requests.

Tiers

Rate Limit Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600

{
  "detail": "Rate limit exceeded"
}

Best Practices

• Implement exponential backoff when receiving 429 responses
• Cache responses when polling the same resource frequently
• Use pagination (per_page up to 200) to reduce request count when fetching large datasets
• Use webhook notifications (when available) instead of polling for changes

All errors follow a consistent JSON format. HTTP status codes reflect standard semantics.

Error Format

{
  "detail": "Human-readable error message"
}

Status Codes

Common Error Messages

All notable changes to the Undercore API are documented here. The API follows semantic versioning.