Synth.Directory

API · Bêta 0.1.1

L'API

Tout dans le répertoire est disponible en JSON : réclamations avec leurs sources et médias, enregistrements, artistes, instruments, recherche, et un moyen de proposer de nouvelles entrées qui arrivent dans la même file de relecture que le site. L'API est en bêta. Version 0.1.1. Les noms et formats de champs peuvent changer à mesure que le répertoire se stabilise ; les changements sont listés en bas de cette page, et le document OpenAPI est toujours le contrat exact actuel.

Obtenir un jeton

  1. Créez un compte et connectez-vous.
  2. Ouvrir Jetons API sous Les miennes et créez-en un. Il est affiché une fois ; il commence par sd_.
  3. Envoyez-le comme jeton porteur à chaque requête.
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

Limites

200 requêtes par heure et par jeton. Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining ; au-delà de la limite, vous recevez un 429 avec un message JSON. Un niveau illimité existe pour les partenaires et le bot du répertoire lui-même ; demandez.

Lecture

Les listes sont paginées : page et per_page (jusqu'à 100), avec next_page dans le corps.

  • 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= · interprètes et producteurs · GET /api/v1/people/{id} · avec leurs crédits acceptés
  • GET /api/v1/search?q= · artistes, enregistrements et instruments en une seule réponse

Statuts : verified, potentially, submitted, inferred (de la base de connaissances, pas encore de source), disputed. Une ligne de réclamation ressemble à une ligne de l'export ci-dessous.

Les presets, notes et favoris sont réservés aux personnes sur le site. Ils ne sont pas dans l'API et ne seront jamais exportés.

Proposer

POST /api/v1/propose met une proposition en file exactement comme le site ; une personne la relit avant toute publication. Le nom du jeton est enregistré sur la proposition afin que les bots soient visibles en relecture.

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

Parties du crédit : réclamation played, programmed · enregistrement produced, engineered, mixed, arranged. Une personne est associée sans tenir compte de la casse, par nom, ou créée. Les crédits sont des faits, donc, contrairement aux presets, ils figurent dans l'API et l'export.

Le répertoire entier

GET /export/manifest.json est public et indique ce qui s'y trouve. GET /export/claims.jsonl diffuse chaque réclamation avec ses sources et médias acceptés, un objet JSON par ligne, avec des filtres since et status. Il nécessite un jeton d'export ; demandez.

Licence

Les faits individuels sont sous CC0. Le répertoire en tant que compilation, et tout extrait substantiel tel que l'export, est sous l'Open Database Licence : créditez le répertoire, et repartagez une base de données que vous en dérivez. Une licence commerciale pour des produits fermés est disponible auprès de Box Of Rules.

Le contrat

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

Changements

  • 0.1.1 (10 septembre 2026) Personnes : crédits d'interprètes et de producteurs sur les réclamations et les enregistrements, points d'accès personnes, propositions de crédits.
  • 0.1.0 (10 septembre 2026) Première bêta : jetons, 200 par heure, lecture des réclamations, enregistrements, artistes, instruments et recherche ; propositions pour réclamations, sources, artistes et enregistrements ; le flux d'export.