Synth.Directory

API · Beta 0.1.1

A API

Tudo no diretório está disponível como JSON: reivindicações com suas fontes e mídia, gravações, artistas, instrumentos, busca, e uma forma de propor novas entradas que caem na mesma fila de revisão que o site. A API está em beta. Versão 0.1.1. Nomes e formatos de campos podem mudar enquanto o diretório se estabiliza; as alterações são listadas no rodapé desta página, e o documento OpenAPI é sempre o contrato exato atual.

Obtendo um token

  1. Crie uma conta e faça login.
  2. Abrir Tokens de API em Minhas e crie um. Ele é mostrado uma vez; começa com sd_.
  3. Envie-o como um bearer token em cada solicitação.
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

Limites

200 solicitações por hora por token. Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining; acima do limite você recebe um 429 com uma mensagem JSON. Existe um nível ilimitado para parceiros e o próprio bot do diretório; pergunte.

Leitura

As listas são paginadas: page e per_page (até 100), com next_page no 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= · intérpretes e produtores · GET /api/v1/people/{id} · com seus créditos aceitos
  • GET /api/v1/search?q= · artistas, gravações e instrumentos em uma resposta

Status: verified, potentially, submitted, inferred (da base de conhecimento, ainda sem fonte), disputed. Uma linha de reivindicação se parece com uma linha da exportação abaixo.

Presets, avaliações e favoritos são apenas para pessoas no site. Eles não estão na API e nunca serão exportados.

Propondo

POST /api/v1/propose coloca uma proposta na fila exatamente como o site faz; uma pessoa a revisa antes que algo seja publicado. O nome do token é registrado na proposta, então bots ficam visíveis na revisão.

{"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 do crédito: reivindicação played, programmed · gravação produced, engineered, mixed, arranged. Uma pessoa é encontrada pelo nome, sem diferenciar maiúsculas de minúsculas, ou criada. Créditos são fatos, então, ao contrário dos presets, eles estão na API e na exportação.

O diretório inteiro

GET /export/manifest.json é público e diz o que há ali. GET /export/claims.jsonl transmite toda reivindicação com suas fontes e mídia aceita, um objeto JSON por linha, com filtros since e status. Precisa de um token de exportação; pergunte.

Licença

Fatos individuais são CC0. O diretório como uma compilação, e qualquer extrato substancial como a exportação, está sob a Open Database Licence: credite o diretório, e compartilhe de volta qualquer banco de dados que você derive dele. Uma licença comercial para produtos fechados está disponível na Box Of Rules.

O contrato

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

Alterações

  • 0.1.1 (10 de setembro de 2026) Pessoas: créditos de intérprete e produtor em reivindicações e gravações, endpoints de pessoas, propostas de crédito.
  • 0.1.0 (10 de setembro de 2026) Primeira beta: tokens, 200 por hora, leitura de reivindicações, gravações, artistas, instrumentos e busca; propostas de reivindicações, fontes, artistas e gravações; o feed de exportação.