Synth.Directory

API · Beta 0.1.1

La API

Todo en el directorio está disponible como JSON: reclamaciones con sus fuentes y medios, discos, artistas, instrumentos, búsqueda, y una forma de proponer nuevas entradas que llegan a la misma cola de revisión que el sitio. La API está en beta. Versión 0.1.1. Los nombres y formas de los campos pueden cambiar a medida que el directorio se asienta; los cambios se enumeran al pie de esta página, y el documento OpenAPI es siempre el contrato exacto actual.

Obtener un token

  1. Cree una cuenta e inicie sesión.
  2. Abrir Tokens de API en Mías y cree uno. Se muestra una sola vez; comienza con sd_.
  3. Envíelo como token de portador en cada solicitud.
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

Límites

200 solicitudes por hora y por token. Cada respuesta lleva X-RateLimit-Limit y X-RateLimit-Remaining; por encima del límite recibe un 429 con un mensaje JSON. Existe un nivel ilimitado para socios y el propio bot del directorio; pregunte.

Lectura

Las listas están paginadas: page y per_page (hasta 100), con next_page en el cuerpo.

  • 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= · intérpretes y productores · GET /api/v1/people/{id} · con sus créditos aceptados
  • GET /api/v1/search?q= · artistas, discos e instrumentos en una sola respuesta

Estados: verified, potentially, submitted, inferred (de la base de conocimiento, aún sin fuente), disputed. Una fila de reclamación se ve como una línea de la exportación de abajo.

Los presets, valoraciones y favoritos son solo para personas en el sitio. No están en la API y nunca se exportarán.

Proponer

POST /api/v1/propose pone en cola una propuesta exactamente como lo hace el sitio; una persona la revisa antes de que se publique nada. El nombre del token queda registrado en la propuesta, de modo que los bots sean visibles en la revisión.

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

Partes del crédito: reclamación played, programmed · disco produced, engineered, mixed, arranged. Una persona se empareja sin distinguir mayúsculas por nombre, o se crea. Los créditos son hechos, así que, a diferencia de los presets, están en la API y en la exportación.

Todo el directorio

GET /export/manifest.json es público y dice qué hay. GET /export/claims.jsonl transmite cada reclamación con sus fuentes y medios aceptados, un objeto JSON por línea, con filtros since y status. Necesita un token de exportación; pregunte.

Licencia

Los hechos individuales están bajo CC0. El directorio como compilación, y cualquier extracto sustancial como la exportación, está bajo la Open Database Licence: acredite al directorio, y comparta de vuelta una base de datos que derive de él. Hay una licencia comercial para productos cerrados disponible en Box Of Rules.

El contrato

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

Cambios

  • 0.1.1 (10 de septiembre de 2026) Personas: créditos de intérpretes y productores en reclamaciones y discos, endpoints de personas, propuestas de créditos.
  • 0.1.0 (10 de septiembre de 2026) Primera beta: tokens, 200 por hora, lectura de reclamaciones, discos, artistas, instrumentos y búsqueda; propuestas para reclamaciones, fuentes, artistas y discos; el feed de exportación.