Referencja API

Publiczne API NexBasira to REST + JSON, wersjonowane pod /api/v1/public/*. Każdy endpoint jest uwierzytelniany parą danych uwierzytelniających cvp_pub:cvp_sec, ograniczony zakresem i paginowany kursorowo tam, gdzie zwraca listę.

Bazowy URL

https://app.nexbasira.com/api/v1/public

W przypadku instalacji self-hosted zamień host na własny. Ścieżka pozostaje taka sama.

Sekcje

Uwierzytelnianie — para danych uwierzytelniających, schemat podpisywania, katalog zakresów
Paginacja + idempotencja — paginacja kursorowa + nagłówek Idempotency-Key
Błędy + limity zapytań — kształt koperty błędu, nagłówki X-RateLimit-*
Sesje — tworzenie, lista, pobieranie, kończenie, zapraszanie
Materiał dowodowy — lista, pobieranie, podpisany URL pobierania
Tablice — lista dla sesji
Endpointy webhooków — rejestracja / rotacja sekretu / wywołanie testowe
Branding — tylko do odczytu w publicznym API; zmiany przez SPA
Organizacja — metadane organizacji tylko do odczytu

Schemat OpenAPI

Przefiltrowana specyfikacja OpenAPI 3.1 (tylko operacje oznaczone tagiem public-api) jest udostępniana pod https://app.nexbasira.com/api/public-schema/. Używaj jej bezpośrednio z generatorami kodu:

# Node typed types
npx openapi-typescript https://app.nexbasira.com/api/public-schema/ -o src/nb-types.ts

# Python typed models
datamodel-codegen \
  --url https://app.nexbasira.com/api/public-schema/ \
  --input-file-type openapi \
  --output-model-type pydantic_v2.BaseModel \
  --output cvp_models.py

Nasze SDK (@nexbasira/node + nexbasira dla Pythona) są zbudowane na tych generowanych typach i dodają ręcznie napisaną ergonomię — typowane błędy, paginację przez async-iterator, funkcje pomocnicze do weryfikacji webhooków.

Stabilność API

Publiczne API stosuje semver według przestrzeni nazw URL. Zmiany łamiące zgodność są wprowadzane pod nowym prefiksem (/api/v2/public/*) z co najmniej 12-miesięcznym okresem nakładania się, zanim poprzednia wersja zostanie wycofana. Zmiany dodające (nowe pola opcjonalne, nowe endpointy, nowe typy zdarzeń) są wprowadzane w miejscu; SDK traktują nieznane pola jako zgodne w przód.