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 на годину, читання тверджень, записів, виконавців, інструментів і пошуку; пропозиції тверджень, джерел, виконавців і записів; стрічка експорту.