# TakeRecord Catalogue Ingest API

> Inbound HTTPS API for pushing a music publishing catalogue (works: titles, recordings, writers, publishers, identifiers) into TakeRecord. Authenticated with a per-client API key. A single endpoint, POST /api/v1/catalogue/works, upserts works; there are no read or export endpoints on this surface.

## Docs

- [API reference (Markdown)](https://ingest.takerecord.com/documentation/catalogue-ingest-api.md): Full reference — authentication, the works upsert endpoint, request/response schema, share semantics, identifier canonicalisation, batching, and idempotency.
- [OpenAPI 3.1 specification](https://ingest.takerecord.com/documentation/catalogue-ingest-api.openapi.yaml): Machine-readable schema for the endpoint, suitable for client and type generation.
- [Rendered reference](https://ingest.takerecord.com/documentation): The same reference as an HTML page.

## Key facts

- Base URL: https://ingest.takerecord.com
- Endpoint: POST /api/v1/catalogue/works
- Auth: "Authorization: Bearer <per-client key>" (create a key in the TakeRecord app under Settings, then API keys)
- Shares are expressed as 0-100. The request schema is strict, so unknown or misspelled fields are rejected.
- Put a stable client_work_ref on each work for safe create-or-update (upsert); send an Idempotency-Key to make a commit safe to retry.
- Preview without persisting using ?dry_run=true (or a body field "mode": "validate").