Synth.Directory

API · Beta 0.1.1

The API

Everything in the directory is available as JSON: claims with their sources and media, records, artists, instruments, search, and a way to propose new entries that lands in the same review queue as the website. The API is in beta. Version 0.1.1. Field names and shapes may change as the directory settles; changes are listed at the foot of this page, and the OpenAPI document is always the exact current contract.

Getting a token

  1. Create an account and log in.
  2. Open API tokens under Mine and make one. It is shown once; it starts with sd_.
  3. Send it as a bearer token on every request.
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

Limits

200 requests an hour per token. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; over the limit you get a 429 with a JSON message. An unlimited tier exists for partners and the directory's own bot; ask.

Reading

Lists are paginated: page and per_page (up to 100), with next_page in the body.

  • GET /api/v1/claims · q, status, origin, artist, instrument, role, since, order · GET /api/v1/claims/{id}
  • GET /api/v1/records · q, artist_id, status=wanted|claimed, since, order, with=claims · GET /api/v1/records/{id}
  • GET /api/v1/artists?q= · GET /api/v1/artists/{id}
  • GET /api/v1/instruments · q, maker, kind · GET /api/v1/instruments/{id}
  • GET /api/v1/people?q= · performers and producers · GET /api/v1/people/{id} · with their accepted credits
  • GET /api/v1/search?q= · artists, records and instruments in one answer

Statuses: verified, potentially, submitted, inferred (from the knowledge base, no source yet), disputed. A claim row looks like one line of the export below.

Presets, ratings and favourites are for people on the website only. They are not in the API and never will be exported.

Proposing

POST /api/v1/propose queues a proposal exactly as the website does; a person reviews it before anything is published. The token name is recorded on the proposal so bots are visible in review.

{"kind": "claim", "work_id": 101, "instrument": "Minimoog", "instrument_maker": "Moog", "role": "lead",
 "source": {"grade": "A", "kind": "interview", "url": "https://...", "publication": "Sound On Sound",
            "author": "...", "published_on": "1983-06-01", "quote": "one sentence, verbatim"}}
{"kind": "source", "claim_id": 202, "source": {...}}
{"kind": "artist", "name": "Tool", "country": "US", "refs": ["https://en.wikipedia.org/...", "https://musicbrainz.org/..."]}
{"kind": "record", "artist_id": 12, "title": "Lateralus", "year": 2001, "refs": ["https://musicbrainz.org/..."]}
{"kind": "credit", "subject": "claim", "id": 202, "person": "Vince Clarke", "part": "played", "note": "on the intro only"}
{"kind": "credit", "subject": "work", "id": 101, "person": "Flood", "part": "produced"}

Credit parts: claim played, programmed · record produced, engineered, mixed, arranged. A person is matched case-insensitively by name or created. Credits are facts, so unlike presets they are in the API and export.

The whole directory

GET /export/manifest.json is public and says what is there. GET /export/claims.jsonl streams every claim with its sources and accepted media, one JSON object a line, with since and status filters. It needs an export token; ask.

Licence

Individual facts are CC0. The directory as a compilation, and any substantial extract such as the export, is under the Open Database Licence: credit the directory, and share back a database you derive from it. A commercial licence for closed products is available from Box Of Rules.

The contract

OpenAPI 3.1 document · llms.txt · ai-catalog.json

Changes

  • 0.1.1 (10 September 2026) People: performer and producer credits on claims and records, people endpoints, credit proposals.
  • 0.1.0 (10 September 2026) First beta: tokens, 200 an hour, reading claims, records, artists, instruments and search; proposals for claims, sources, artists and records; the export feed.