Synth.Directory

API · Beta 0.1.1

L'API

Tutto nella directory è disponibile come JSON: richieste con le loro fonti e media, dischi, artisti, strumenti, ricerca, e un modo per proporre nuove voci che finiscono nella stessa coda di revisione del sito. L'API è in beta. Versione 0.1.1. I nomi e le forme dei campi possono cambiare man mano che la directory si assesta; le modifiche sono elencate in fondo a questa pagina, e il documento OpenAPI è sempre il contratto esatto attuale.

Ottenere un token

  1. Crei un account e acceda.
  2. Apri Token API sotto Le mie e ne crei uno. Viene mostrato una volta sola; inizia con sd_.
  3. Lo invii come token bearer in ogni richiesta.
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

Limiti

200 richieste all'ora per token. Ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining; oltre il limite si riceve un 429 con un messaggio JSON. Esiste un livello illimitato per i partner e il bot della directory stessa; chieda.

Lettura

Gli elenchi sono paginati: page e per_page (fino a 100), con next_page nel corpo.

  • 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= · interpreti e produttori · GET /api/v1/people/{id} · con i loro crediti accettati
  • GET /api/v1/search?q= · artisti, dischi e strumenti in un'unica risposta

Stati: verified, potentially, submitted, inferred (dalla banca dati di conoscenza, ancora nessuna fonte), disputed. Una riga di richiesta è come una riga dell'export qui sotto.

I preset, le valutazioni e i preferiti sono solo per le persone sul sito. Non sono nell'API e non verranno mai esportati.

Proporre

POST /api/v1/propose mette in coda una proposta esattamente come fa il sito; una persona la rivede prima che venga pubblicato qualcosa. Il nome del token viene registrato sulla proposta, così i bot sono visibili in revisione.

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

Parti del credito: richiesta played, programmed · disco produced, engineered, mixed, arranged. Una persona viene associata senza distinguere maiuscole e minuscole in base al nome, o creata. I crediti sono fatti, quindi, a differenza dei preset, sono nell'API e nell'export.

L'intera directory

GET /export/manifest.json è pubblico e indica cosa c'è. GET /export/claims.jsonl trasmette ogni richiesta con le sue fonti e i media accettati, un oggetto JSON per riga, con filtri since e status. Richiede un token di export; chieda.

Licenza

I singoli fatti sono sotto CC0. La directory come compilazione, e ogni estratto sostanziale come l'export, è sotto la Open Database Licence: citi la directory, e condivida a sua volta una banca dati che ne derivi. Una licenza commerciale per prodotti chiusi è disponibile presso Box Of Rules.

Il contratto

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

Modifiche

  • 0.1.1 (10 settembre 2026) Persone: crediti di interpreti e produttori su richieste e dischi, endpoint delle persone, proposte di crediti.
  • 0.1.0 (10 settembre 2026) Prima beta: token, 200 all'ora, lettura di richieste, dischi, artisti, strumenti e ricerca; proposte per richieste, fonti, artisti e dischi; il feed di export.