API Reference
Endpoint-by-endpoint dokumentace pro StellarCloud. OpenAI-compatible kde to jde. REST + JSON end-to-end.
Base URL
Managed nasazení: https://api.stellarcloud.ai/v1
Self-hosted nasazení: https://your-domain/v1
Verzování je path-based. Breaking changes posunou na /v2 s minimálně 12měsíčním okénkem deprecation.
Autentizace
Bearer token v hlavičce Authorization. API klíče se spravují v admin UI s per-key scope, rate limits a expirací.
Klíče jsou buď organization-wide, nebo Base-scoped. Best practice: jeden klíč per služba / aplikace, rotovaný čtvrtletně.
Přehled endpointů
Chat & completions
| Endpoint | Účel |
|---|---|
POST /chat/completions | OpenAI-compatible chat completion |
POST /completions | Legacy text completion (nedoporučované) |
POST /embeddings | OpenAI-compatible embeddings |
Specifické pro StellarCloud
| Endpoint | Účel |
|---|---|
POST /ocr | StellarOCR — dokument na strukturovaný výstup |
POST /detect-language | Detekce jazyka |
POST /ner | Rozpoznávání pojmenovaných entit |
POST /entity-linking | Linkování entit na kanonická ID |
POST /lemmatize | Lemmatizace |
POST /rerank | Cross-encoder re-ranking |
POST /image-embeddings | Obrazové embeddings |
Platforma
| Endpoint | Účel |
|---|---|
POST /search | Hybridní vyhledávání nad Base |
POST /sources | Správa konektorů datových zdrojů |
POST /agents | Vytvoření / update agentů |
POST /workflows/<id>/trigger | Spuštění workflow |
GET /audit-log | Dotaz nad audit logem |
StellarGate
| Endpoint | Účel |
|---|---|
POST /gate/anonymize | Režim 2 — anonymizace bez přeposlání |
POST /gate/deanonymize | Režim 2 — rozkódování tokenů s map_id |
POST /gate/dictionaries | Správa vlastních slovníků |
POST /gate/hitl/queue | HITL schvalovací fronta |
Pro Režim 1 (transparent proxy) použijte POST /chat/completions — StellarGate řeší anonymizaci transparentně.
Konvence requestu / odpovědi
- Všechny requesty a odpovědi jsou JSON, kódované v UTF-8
- Timestampy jsou ISO 8601 v UTC
- ID jsou neprůhledné řetězce, case-sensitive
- Stránkování přes
cursorparametr;next_cursorv odpovědi - Rate limity komunikované přes hlavičky
X-RateLimit-*
Chyby
Standardní HTTP status kódy + JSON error body:
| Status | Význam |
|---|---|
| 400 | Bad request — neplatný JSON nebo parametry |
| 401 | Chybějící nebo neplatný API klíč |
| 403 | API klíč nemá oprávnění ke zdroji |
| 404 | Zdroj nenalezen |
| 409 | Conflict (např. souběžná úprava) |
| 422 | Vstup neprošel validací schématu |
| 429 | Rate limit překročen — opakujte po Retry-After sekundách |
| 500 | Vnitřní chyba serveru — pokud trvá, ohlaste podpoře |
| 502 / 503 | Upstream provider nedostupný |
Error body: code (strojově čitelný), message (lidsky čitelný), request_id (pro korelaci s podporou).
Rate limity
Defaults:
- 50 requestů za sekundu per API klíč
- 100 souběžných spojení per API klíč
- Denní spending cap konfigurovatelný per klíč
Vyšší limity na vyžádání.
Streamování
Chat completions podporují Server-Sent Events (SSE) streaming přes stream: true. Jednotlivé tokeny se streamují ve standardním OpenAI SSE formátu. Končí data: [DONE].
Idempotence
Non-idempotentní endpointy (POST, který vytváří zdroje) přijímají hlavičku Idempotency-Key. Pokud uvidíme stejný klíč do 24 hodin, vrátíme cached odpověď, místo abychom re-execute.
Webhooks
Pro déle běžící operace (velké OCR joby, běhy workflow) webhooks notifikují váš endpoint o dokončení. Nakonfigurujte webhook URL v admin UI. Payloady jsou HMAC-signed — ověřte podpis, než tomu budete věřit.
SDK
Oficiální SDK obalují REST API ergonomií konkrétního jazyka:
- Python —
stellarbasena PyPI - TypeScript / Node —
@stellarbase/sdkna npm - Go, Java, .NET, Rust — beta
Všechny SDK podporují OpenAI compatibility vrstvu — pokud už používáte openai-python nebo openai-node, minimální změna je jen base URL.
OpenAPI spec
Plný OpenAPI 3.1 spec dostupný na https://api.stellarcloud.ai/v1/openapi.json. Importujte do Postmana, Insomnie nebo libovolného code-generatoru pro scaffold klientského kódu.