Synth.Directory

API · Bèta 0.1.1

De API

Alles in de directory is beschikbaar als JSON: beweringen met hun bronnen en media, opnames, artiesten, instrumenten, zoeken, en een manier om nieuwe items voor te stellen die in dezelfde beoordelingswachtrij terechtkomen als de website. De API is in bèta. Versie 0.1.1. Veldnamen en -vormen kunnen veranderen terwijl de directory zich zet; wijzigingen staan onderaan deze pagina vermeld, en het OpenAPI-document is altijd het exacte huidige contract.

Een token verkrijgen

  1. Maak een account aan en log in.
  2. Openen API-tokens onder Mijn en maak er een aan. Wordt eenmalig getoond; begint met sd_.
  3. Stuur het als bearer-token mee bij elk verzoek.
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

Limieten

200 aanvragen per uur per token. Elk antwoord draagt X-RateLimit-Limit en X-RateLimit-Remaining; boven de limiet krijgt u een 429 met een JSON-bericht. Er bestaat een onbeperkt niveau voor partners en de eigen bot van de directory; vraag ernaar.

Lezen

Lijsten zijn gepagineerd: page en per_page (tot 100), met next_page in de 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= · uitvoerenden en producers · GET /api/v1/people/{id} · met hun geaccepteerde credits
  • GET /api/v1/search?q= · artiesten, opnames en instrumenten in één antwoord

Statussen: verified, potentially, submitted, inferred (uit de kennisbank, nog geen bron), disputed. Een beweringsregel ziet eruit als één regel van de export hieronder.

Presets, beoordelingen en favorieten zijn alleen voor mensen op de website. Ze staan niet in de API en worden nooit geëxporteerd.

Voorstellen

POST /api/v1/propose plaatst een voorstel in de wachtrij precies zoals de website dat doet; een persoon beoordeelt het voordat er iets wordt gepubliceerd. De tokennaam wordt op het voorstel vastgelegd, zodat bots zichtbaar zijn bij de beoordeling.

{"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"}

Creditonderdelen: bewering played, programmed · opname produced, engineered, mixed, arranged. Een persoon wordt hoofdletterongevoelig gekoppeld op naam, of aangemaakt. Credits zijn feiten, dus in tegenstelling tot presets staan ze in de API en de export.

De hele directory

GET /export/manifest.json is openbaar en laat zien wat er is. GET /export/claims.jsonl streamt elke bewering met de bronnen en geaccepteerde media, één JSON-object per regel, met since- en status-filters. Er is een exporttoken voor nodig; vraag ernaar.

Licentie

Individuele feiten staan onder CC0. De directory als compilatie, en elk substantieel uittreksel zoals de export, valt onder de Open Database Licence: vermeld de directory, en deel een database die u eruit afleidt terug. Een commerciële licentie voor gesloten producten is verkrijgbaar bij Box Of Rules.

Het contract

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

Wijzigingen

  • 0.1.1 (10 september 2026) Personen: uitvoerder- en producercredits op beweringen en opnames, persoon-endpoints, creditvoorstellen.
  • 0.1.0 (10 september 2026) Eerste bèta: tokens, 200 per uur, lezen van beweringen, opnames, artiesten, instrumenten en zoeken; voorstellen voor beweringen, bronnen, artiesten en opnames; de exportfeed.