API Reference

Base URL https://ingest.takerecord.comAuth Bearer trk_live_...

Upsert one to 500 works into a catalogue.

Request body · application/json

client_idstringlength 1–∞

If present, must match the client bound to the API key.

client_artist_refstringlength 1–255

Your stable artist or account-holder id, such as your platform user_id. This is a top-level request body field, not a header and not a per-work field. When catalog_id is omitted, new works route to the existing catalogue for this ref, adopt the one existing catalogue matched by the batch on commit, or create it on first commit. If both catalog_id and client_artist_ref are sent, catalog_id wins.

catalog_namestring

Names a new catalogue. Default is API Import YYYY-MM-DD.

catalog_idstring

Append to an existing catalogue. A new one is created if omitted. 404 if not this client's. If both catalog_id and client_artist_ref are sent, catalog_id wins.

modestring

The value validate is a dry-run; commit (the default) persists.

validatecommit

worksarray of WorkInputrequired1–500 items

Headers

Idempotency-Keystring

Unique per request (a UUID is ideal); one key per chunk when paging. Same key with the same body replays the original response (with header Idempotent-Replay: true); same key while still processing returns 409; same key with a different body returns 422. Retained 24h. Ignored in dry-run.

x-client-idstring

Optional. If present, must equal the client bound to the API key, else 403.

Query parameters

dry_runboolean

When true, validate and report without persisting (equivalent to body mode=validate). Returns 200.

Request

curl -X POST https://ingest.takerecord.com/api/v1/catalogue/works \
  -H "Authorization: Bearer $RECORD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @works.json

Responses

200Dry-run (validate) result. Nothing persisted; no catalogue or client_artist_ref mapping is created, work_ids is empty, and each results[].work_id is null.

201Commit result. Works persisted.

400Validation failed (an unknown/misspelled field, a duplicate client_work_ref in the batch, an invalid publisher-to-writer link, a share outside the 0-100 range, a body client_id that does not match the key, or a client_artist_ref conflict with existing catalogue state).

401Missing, invalid, expired, or revoked API key.

403Not a per-client key, missing scope, or x-client-id header mismatch.

404catalog_id is not one of this client's catalogues.

409An Idempotency-Key is still being processed.

422An Idempotency-Key was reused with a different request body.

429Rate limit exceeded (60 requests per minute per key).

500Unexpected server error.

{
  "catalog_id": "cat-9f2a1b3c",
  "catalog_name": "My catalogue",
  "mode": "commit",
  "works_created": 1,
  "works_updated": 0,
  "works_skipped": 0,
  "work_ids": ["REC-2026-00001"],
  "results": [
    { "client_work_ref": "ACME-0001", "work_id": "REC-2026-00001", "action": "created" }
  ],
  "gaps": [],
  "validation": { "total_works": 1, "works_flagged": 0, "attestation_ran": true, "issues": [] },
  "roster_adjusted": 0,
  "prose_stripped": 0,
  "canonicalised": 1
}