platform-api reference
Generated from the live spec at https://api.v2.nairon.xyz/openapi.json (version 0.2.5 at time
of writing). Full machine-readable spec:
platform-api.openapi.json.
Authentication
Section titled “Authentication”Every route except /health accepts a secret API key as either:
Authorization: Bearer nrn_sk_...x-api-key: nrn_sk_...
POST /v1/chat/completions
Section titled “POST /v1/chat/completions”OpenAI chat-completions-compatible. Unknown fields pass through to the upstream provider.
Request (ChatCompletionRequest):
| Field | Type | Notes |
|---|---|---|
model | string, required | A catalogue model tag, or "auto". |
messages | ChatMessage[], required | { role, content } — content may be a string or content-part array. |
stream | boolean, default false | SSE streaming. |
reasoning | "turbo" | "fast" | "balanced" | "smart", optional | Consulted only when model == "auto"; never forwarded upstream. |
POST /v1/audio/speech
Section titled “POST /v1/audio/speech”OpenAI /v1/audio/speech-compatible.
| Field | Type | Notes |
|---|---|---|
input | string, required | Text to synthesize. |
voice | string, optional | A Nairon agent_voices id or name. |
model | string, optional | |
response_format | string, default "wav" | |
speed | number, optional | |
stream | boolean, default true | Streamed chunked audio. |
POST /v1/audio/transcriptions
Section titled “POST /v1/audio/transcriptions”Multipart upload.
| Field | Type | Notes |
|---|---|---|
file | binary, required | |
model | string, default "auto" | |
language | string, optional | |
response_format | string, default "json" | "json" guarantees only text; "verbose_json" adds segments/language/duration. |
Response (TranscriptionResponse): { text, ... }.
Knowledge base stores
Section titled “Knowledge base stores”| Method & path | Purpose |
|---|---|
GET /v1/stores | List stores. |
POST /v1/stores | Create a store — { name, description? }. |
GET /v1/stores/{store_id} | Get a store. |
DELETE /v1/stores/{store_id} | Delete a store. |
POST /v1/stores/{store_id}/information | Add content — { name, sourceType: "website"|"file", source, description?, crawlMode? }. |
GET /v1/stores/{store_id}/information | List content items. |
DELETE /v1/stores/{store_id}/information/{information_id} | Remove a content item. |
POST /v1/stores/{store_id}/query | Similarity search — { query, top_k? (default 6, max 50), score_threshold? (default 0.35) } → { chunks: [{ text, score, metadata }] }. |
StoreResponse: { id, name, description?, status, createdAt, updatedAt }.
InformationResponse: { id, knowledgeBaseId, name, sourceType, source, crawlMode, indexingStatus, indexingProgress, createdAt, updatedAt }.
Files & batches
Section titled “Files & batches”| Method & path | Purpose |
|---|---|
POST /v1/files | Upload a file (multipart) for batch input. |
GET /v1/files | List files. |
GET /v1/files/{file_id} | Get file metadata. |
DELETE /v1/files/{file_id} | Delete a file. |
GET /v1/files/{file_id}/content | Download file content (e.g. batch output JSONL). |
POST /v1/batches | Create a batch — { input_file_id, endpoint, completion_window? (default "24h"), metadata? }. |
GET /v1/batches | List batches. |
GET /v1/batches/{batch_id} | Get batch status. |
POST /v1/batches/{batch_id}/cancel | Cancel a batch. |
Batch lifecycle follows the OpenAI Batch object model: validating → in_progress → completed/failed/expired/cancelled.
Realtime
Section titled “Realtime”There is no realtime path in the OpenAPI document (it’s a WebSocket upgrade, not a documented REST route) — see Developer guide → Realtime for how to connect.
Health & introspection
Section titled “Health & introspection”| Method & path | Purpose |
|---|---|
GET /health | Liveness check. |
GET /v1/me | WhoAmIResponse: { apiKeyId, projectId, organizationId, keyType } for the presented key. |