Synth.Directory

API · Beta 0.1.1

API

Wszystko w katalogu jest dostępne jako JSON: twierdzenia z ich źródłami i mediami, nagrania, artyści, instrumenty, wyszukiwanie oraz sposób proponowania nowych wpisów, które trafiają do tej samej kolejki weryfikacji co strona. API jest w wersji beta. Wersja 0.1.1. Nazwy i kształty pól mogą się zmieniać w miarę stabilizowania się katalogu; zmiany są wymienione u dołu tej strony, a dokument OpenAPI zawsze stanowi dokładnie aktualną umowę.

Uzyskiwanie tokenu

  1. Utwórz konto i zaloguj się.
  2. Otwórz Tokeny API w sekcji Moje i utwórz jeden. Jest pokazywany raz; zaczyna się od sd_.
  3. Wysyłaj go jako token bearer w każdym żądaniu.
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

Limity

200 żądań na godzinę na token. Każda odpowiedź zawiera X-RateLimit-Limit i X-RateLimit-Remaining; po przekroczeniu limitu otrzymujesz 429 z komunikatem JSON. Dla partnerów i własnego bota katalogu istnieje poziom bez limitu; zapytaj.

Odczyt

Listy są stronicowane: page i per_page (do 100), z next_page w treści.

  • 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= · wykonawcy i producenci · GET /api/v1/people/{id} · z ich zaakceptowanym udziałem
  • GET /api/v1/search?q= · artyści, nagrania i instrumenty w jednej odpowiedzi

Statusy: verified, potentially, submitted, inferred (z bazy wiedzy, jeszcze bez źródła), disputed. Wiersz twierdzenia wygląda jak jeden wiersz eksportu poniżej.

Presety, oceny i ulubione są tylko dla ludzi na stronie. Nie ma ich w API i nigdy nie będą eksportowane.

Proponowanie

POST /api/v1/propose dodaje propozycję do kolejki dokładnie tak, jak robi to strona; osoba weryfikuje ją, zanim cokolwiek zostanie opublikowane. Nazwa tokenu jest zapisywana przy propozycji, więc boty są widoczne podczas weryfikacji.

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

Role udziału: twierdzenie played, programmed · nagranie produced, engineered, mixed, arranged. Osoba jest dopasowywana po nazwisku bez rozróżniania wielkości liter albo tworzona od nowa. Udział jest faktem, więc w przeciwieństwie do presetów znajduje się w API i eksporcie.

Cały katalog

GET /export/manifest.json jest publiczny i mówi, co się tam znajduje. GET /export/claims.jsonl przesyła strumieniowo każde twierdzenie z jego źródłami i zaakceptowanymi mediami, jeden obiekt JSON na wiersz, z filtrami since i status. Wymaga tokenu eksportu; zapytaj.

Licencja

Poszczególne fakty są objęte CC0. Katalog jako kompilacja, oraz każdy istotny wyciąg, taki jak eksport, podlega licencji Open Database Licence: podaj katalog jako źródło i udostępnij z powrotem bazę danych, którą z niego wyprowadzisz. Licencja komercyjna dla zamkniętych produktów jest dostępna w Box Of Rules.

Umowa

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

Zmiany

  • 0.1.1 (10 września 2026) Osoby: udział wykonawców i producentów w twierdzeniach i nagraniach, punkty końcowe dla osób, propozycje udziału.
  • 0.1.0 (10 września 2026) Pierwsza beta: tokeny, 200 na godzinę, odczyt twierdzeń, nagrań, artystów, instrumentów i wyszukiwania; propozycje twierdzeń, źródeł, artystów i nagrań; kanał eksportu.