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

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
}

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.