Αναφορά API

Το δημόσιο API του NexBasira είναι REST + JSON, με έκδοση υπό το /api/v1/public/*. Κάθε endpoint αυθεντικοποιείται μέσω του ζεύγους διαπιστευτηρίων cvp_pub:cvp_sec, περιορίζεται με scope και σελιδοποιείται με cursor όπου επιστρέφει λίστα.

Base URL

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

Για εγκαταστάσεις self-hosted, αντικαταστήστε τον host με τον δικό σας. Το path παραμένει το ίδιο.

Ενότητες

• Αυθεντικοποίηση — ζεύγος διαπιστευτηρίων, σχήμα υπογραφής, κατάλογος scope
• Σελιδοποίηση + idempotency — σελιδοποίηση με cursor + κεφαλίδα Idempotency-Key
• Σφάλματα + όρια ρυθμού — μορφή φακέλου σφάλματος, κεφαλίδες X-RateLimit-*
• Συνεδρίες — δημιουργία, λίστα, ανάκτηση, τερματισμός, πρόσκληση
• Τεκμήρια — λίστα, ανάκτηση, υπογεγραμμένο URL λήψης
• Whiteboards — λίστα ανά συνεδρία
• Endpoints Webhook — καταχώριση / εναλλαγή μυστικού / δοκιμαστική αποστολή
• Branding — μόνο για ανάγνωση στο δημόσιο API· μεταβολές μέσω του SPA
• Org — μεταδεδομένα org μόνο για ανάγνωση

Σχήμα OpenAPI

Μια φιλτραρισμένη spec OpenAPI 3.1 (μόνο οι λειτουργίες με ετικέτα public-api) διατίθεται στο https://app.nexbasira.com/api/public-schema/. Χρησιμοποιήστε την απευθείας με γεννήτριες κώδικα:

# 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

Τα SDK μας (@nexbasira/node + nexbasira για Python) βασίζονται πάνω σε αυτούς τους παραγόμενους τύπους και προσθέτουν χειρόγραφη εργονομία — typed errors, σελιδοποίηση async-iterator, βοηθητικές συναρτήσεις επαλήθευσης webhook.

Σταθερότητα API

Το δημόσιο API ακολουθεί semver ανά namespace URL. Οι breaking αλλαγές διατίθενται υπό νέο prefix (/api/v2/public/*) με τουλάχιστον 12 μήνες επικάλυψης πριν αποσυρθεί η προηγούμενη έκδοση. Οι προσθετικές αλλαγές (νέα προαιρετικά πεδία, νέα endpoints, νέοι τύποι συμβάντων) διατίθενται επιτόπου· τα SDK αντιμετωπίζουν άγνωστα πεδία ως συμβατά προς τα εμπρός.