Developer reference

The CWR Check API

Everything the site does is an HTTP call you can make yourself: validate CWR files, check a catalog for free, and generate delivery-ready CWR 2.1/2.2. If /api/lint comes back clean, /api/generate is guaranteed to succeed with the same input. Everything is free while the service is in open beta.

Endpoints

No authentication, no signup: every endpoint is free to call within the rate limits while the service is in open beta.

Interactive documentation

Try every endpoint from the browser with Swagger UI, read the reference in ReDoc, or import the OpenAPI description into Postman, Insomnia, or a code generator.

Quick start

Check a catalog (start from the example):

curl -X POST https://cwrcheck.com/api/lint \
  -H "Content-Type: application/json" \
  -d @catalog.json

Generate and download the CWR file:

curl -X POST https://cwrcheck.com/api/generate \
  -H "Content-Type: application/json" \
  -d @catalog.json -OJ

Validate an existing CWR file:

curl -X POST https://cwrcheck.com/api/validate \
  -F "files=@CW260001XXX_BMI.V21"

Python:

import requests

catalog = {
    "sender": {"type": "PB", "id": 123456789, "name": "EXAMPLE MUSIC"},
    "receiver": "BMI",
    "works": [{
        "title": "EXAMPLE SONG",
        "submitter_work_number": "EX0001",
        "writers": [{"ip_number": "W1", "last_name": "DOE",
                     "pr_share": 100}],
    }],
}

# Free check first: clean lint guarantees generation succeeds.
lint = requests.post("https://cwrcheck.com/api/lint", json=catalog).json()
assert lint["ok"], lint

r = requests.post("https://cwrcheck.com/api/generate", json=catalog)
r.raise_for_status()
open(lint["filename"], "w").write(r.text)

JavaScript:

const catalog = { /* same shape as the Python example */ };

const lint = await fetch("https://cwrcheck.com/api/lint", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(catalog),
}).then((r) => r.json());
if (!lint.ok) throw new Error(JSON.stringify(lint.schema_errors));

const cwr = await fetch("https://cwrcheck.com/api/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(catalog),
});
const file = await cwr.text(); // fixed-width CWR, filename in
                               // the Content-Disposition header

Exports

The same validation, as a spreadsheet. Add format=csv and table= to /api/validate and one file comes back as text/csv with the filename in Content-Disposition:

curl -X POST \
  "https://cwrcheck.com/api/validate?format=csv&table=parties" \
  -F "files=@CW260001XXX_BMI.V21" -OJ

Files are UTF-8 with a byte-order mark and RFC 4180 quoting, so Japanese and Korean titles open correctly in Excel. Unlike the HTML report, exports are never truncated — the whole catalog goes in the file. The column contract is versioned: this is v1, returned on every export in the X-Export-Contract-Version header. Columns are only ever appended within a version; removing, renaming, or reordering one bumps it. Pass lang=ja|ko|es|de to localize the explanation columns of the findings table; the CWR spec’s own message and a society’s message_text are always verbatim.

works

Every work registration in the file, with its share totals and its finding counts. Row grain: one row per work transaction (NWR, REV, ISW, EXC).

parties

Every publisher and writer on every work, with ownership, collection, territories, and the net owned share. Row grain: one row per party per work.

findings

Every finding, with the spec's own wording and the plain-language explanation in your language. Row grain: one row per finding.

ack

What the society said about each work you sent, one row per message. Row grain: one row per acknowledgement message, or one row per acknowledged work where the society sent no message.

societies

Every society code the file references, and how often. Row grain: one row per distinct society code.

Rate limits

Limits are per client, per minute. Exceeding one returns 429 with Retry-After and X-RateLimit-* headers saying exactly when to retry. CORS is enabled, so the API is callable directly from browser apps. Need more throughput? Ask.

Responses and errors

A successful /api/lint looks like this — ok: true is the guarantee that /api/generate will succeed with the same input:

{
  "ok": true,
  "works": 3,
  "filename": "CW260001KTG_BMI.V21",
  "schema_errors": [],
  "generator_error": null,
  "writers": {"distinct": 2, "omitted": 0, "rows": [
    {"name": "JANE DOE", "ipi": "00014107338", "works": 2,
     "advisories": ["writer-name-several-ipis"],
     "paths": ["/works/0/writers/0", "/works/2/writers/1"], "…": "…"}
  ]},
  "writer_advisories": [
    {"code": "writer-name-several-ipis",
     "paths": ["/works/0/writers/0", "/works/2/writers/1"], "…": "…"}
  ]
}

A clean catalog also comes back with its writers and the questions it raises about them (writer_advisories), each pointing at the catalog by JSON path. They are advisories: they never change ok or block generation. Add ?writer_check=true to look the writers up on Songlinks as well, exactly as /api/validate does.

A failing one names every problem with its JSON path (schema_errors) or a plain-English generator message. Every non-2xx response is a JSON envelope {"detail": "…"} with a human-readable explanation:

The catalog format

A catalog is one JSON object describing your works. All shares are percentages (50 or 33.34); everything the CWR format needs beyond this — record prefixes, sequence numbers, control totals, territory records — is derived for you. The machine-readable source of truth is catalog-v1.json (JSON Schema 2020-12; point your editor's $schema at it for autocomplete). Version policy: v1 only ever gains fields; breaking changes would ship as catalog-v2.json.

Catalog

A work catalog accepted by cwrcheck.com's CWR generation service (POST /api/generate). Version 1: additive changes only; breaking changes will publish catalog-v2.json.

Work

Writer

Publisher

Territory

Alternate title

Questions the reference doesn’t answer: alex@kanetechgroup.com — a human replies within one business day.