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.

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.

modestring

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

validatecommit

worksrequiredarray of WorkInput1–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 $TAKERECORD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @works.json

Responses

200Dry-run (validate) result. Nothing persisted; work_ids is empty and each results[].work_id is null.

201Commit result. Works persisted.

400Validation failed (an unknown/misspelled field, a share outside the 0-100 range, or a body client_id that does not match the key).

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
}