Synth.Directory

API · Бета 0.1.1

API

Всё в каталоге доступно как JSON: утверждения с их источниками и медиа, записи, исполнители, инструменты, поиск, а также способ предложить новые записи, которые попадают в ту же очередь на проверку, что и на сайте. API находится в бета-версии. Версия 0.1.1. Названия и структура полей могут меняться по мере становления каталога; изменения перечислены внизу этой страницы, а документ OpenAPI всегда отражает точный текущий контракт.

Получение токена

  1. Создайте аккаунт и войдите.
  2. Открыть Токены API в разделе Моё и создайте его. Он показывается один раз; начинается с sd_.
  3. Отправляйте его как bearer-токен в каждом запросе.
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

Лимиты

200 запросов в час на токен. Каждый ответ содержит X-RateLimit-Limit и X-RateLimit-Remaining; при превышении лимита вы получаете 429 с сообщением JSON. Для партнёров и собственного бота каталога существует безлимитный уровень; спрашивайте.

Чтение

Списки постранично разбиты: page и per_page (до 100), с next_page в теле ответа.

  • 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= · исполнители и продюсеры · GET /api/v1/people/{id} · с принятыми данными об участии
  • GET /api/v1/search?q= · исполнители, записи и инструменты в одном ответе

Статусы: verified, potentially, submitted, inferred (из базы знаний, пока без источника), disputed. Строка утверждения выглядит как одна строка экспорта ниже.

Пресеты, оценки и избранное - только для людей на сайте. Их нет в API, и они никогда не будут экспортированы.

Предложение

POST /api/v1/propose ставит предложение в очередь точно так же, как это делает сайт; человек проверяет его прежде, чем что-либо публикуется. Имя токена записывается в предложении, поэтому боты видны при проверке.

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

Роли участия: утверждение played, programmed · запись produced, engineered, mixed, arranged. Человек определяется по имени без учёта регистра или создаётся заново. Данные об участии — это факты, поэтому, в отличие от пресетов, они есть в API и в экспорте.

Весь каталог

GET /export/manifest.json публичен и сообщает, что там есть. GET /export/claims.jsonl передаёт поток каждого утверждения с его источниками и принятыми медиа, по одному JSON-объекту на строку, с фильтрами since и status. Требуется токен экспорта; спрашивайте.

Лицензия

Отдельные факты - CC0. Каталог как сборник, и любое существенное извлечение, например экспорт, распространяется по лицензии Open Database Licence: указывайте каталог как источник и делитесь в ответ базой данных, производной от него. Коммерческая лицензия для закрытых продуктов доступна у Box Of Rules.

Контракт

Документ OpenAPI 3.1 · llms.txt · ai-catalog.json

Изменения

  • 0.1.1 (10 сентября 2026) Люди: данные об участии исполнителей и продюсеров в утверждениях и записях, конечные точки для людей, предложения об участии.
  • 0.1.0 (10 сентября 2026) Первая бета: токены, 200 в час, чтение утверждений, записей, исполнителей, инструментов и поиск; предложения утверждений, источников, исполнителей и записей; лента экспорта.