Quickstart

This page takes you from nothing to a stored work. It uses one song, so you can read every field in the response. Load a full catalogue covers thousands of works.

Prerequisites#

• A Record account.
• An API key. Get your Record API key shows you how to create one.

Export the key. It starts with trk_live_.

export TRK_API_KEY="trk_live_..."

Send your first request#

Start with ?dry_run=true. We store nothing. You still get the same gap and validation reports that a real commit returns, so you can check your field mapping before any data lands.

curl -X POST "https://ingest.takerecord.com/api/v1/catalogue/works?dry_run=true" \
  -H "Authorization: Bearer $TRK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_name": "My first catalogue",
    "works": [
      {
        "primary_title": "Midnight Drive",
        "client_work_ref": "ACME-0001",
        "recording": { "artist_name": "Nova Ray", "isrc": "USRC12345678" },
        "writers": [
          { "writer_first_name": "Alex", "writer_last_name": "Stone", "writer_ownership_pct": 100, "writer_controlled": true }
        ],
        "publishers": [
          {
            "publisher_name": "Acme Publishing",
            "publisher_collection_share": 50,
            "linked_writer_index": 0,
            "publisher_controlled": true
          }
        ]
      }
    ]
  }'

Read the response#

A dry-run returns 200.

{
  "catalog_id": "",
  "catalog_name": "My first catalogue",
  "mode": "validate",
  "works_created": 0,
  "work_ids": [],
  "results": [{ "client_work_ref": "ACME-0001", "work_id": null, "action": "created" }],
  "gaps": [{ "work_index": 0, "title": "Midnight Drive", "missing_fields": ["iswc", "writer_ipi"] }],
  "validation": { "total_works": 1, "works_flagged": 0, "attestation_ran": true, "issues": [] }
}

Read gaps before you go on. It lists what this work is missing. It does not list what is wrong with it. Validation and gaps explains both reports.

In a dry-run catalog_id is empty when the request would create a new catalogue. Do not store that value.

Commit the work#

Remove ?dry_run=true and add an Idempotency-Key. The key makes a network retry safe. The same key with the same body replays the first result instead of a second write.

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

A commit returns 201.

{
  "catalog_id": "cat-a1b2c3d4",
  "mode": "commit",
  "works_created": 1,
  "works_updated": 0,
  "work_ids": ["REC-2026-00001"],
  "results": [{ "client_work_ref": "ACME-0001", "work_id": "REC-2026-00001", "action": "created" }]
}

Store results[].work_id against your own client_work_ref. That pair is how you reconcile our records with yours later.

What to do next#

Send the same client_work_ref again with more fields. The work updates in place. You do not create a duplicate, and you do not need to store our catalog_id to do it.