platform-api (OpenAI-compatible)

platform-api is Nairon’s data plane, hosted at https://api.v2.nairon.xyz. Its /v1 surface is intentionally OpenAI-compatible — point an OpenAI SDK’s base_url at it and existing client code mostly works unchanged.

Authenticate with a secret API key (nrn_sk_...) minted on platform.v2.nairon.xyz, either as Authorization: Bearer nrn_sk_... or an x-api-key header.

Chat completions

POST /v1/chat/completions — OpenAI chat-completions-compatible; unknown fields pass through to the upstream provider. model accepts a catalogue model tag or "auto". When model is "auto", an optional Nairon-specific reasoning field (turbo | fast | balanced | smart) steers automatic model selection — it is never forwarded upstream.

from openai import OpenAI

client = OpenAI(api_key="NAIRON_API_KEY", base_url="https://api.v2.nairon.xyz/v1")

resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Summarize this call in one sentence."}],
    extra_body={"reasoning": "balanced"},
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="")

Speech (text-to-speech)

POST /v1/audio/speech — OpenAI /v1/audio/speech-compatible; voice is a Nairon agent_voices id or name. Streams chunked audio by default (stream: true).

curl -X POST https://api.v2.nairon.xyz/v1/audio/speech \
  -H "Authorization: Bearer NAIRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello from Nairon.", "voice": "your-agent-voice-id", "response_format": "wav"}' \
  --output speech.wav

Transcriptions

POST /v1/audio/transcriptions — multipart upload, OpenAI-compatible.

audio_file = open("call.wav", "rb")
transcript = client.audio.transcriptions.create(model="auto", file=audio_file)
print(transcript.text)

Realtime (speech-to-speech)

A WebSocket endpoint speaking the server side of the OpenAI Realtime event protocol (session.update, input_audio_buffer.append/commit, response.create, and the corresponding response.audio.delta / response.done events), built on pipecat with server-side VAD. Use the OpenAI client’s realtime support with a websocket_base_url override pointed at this host. Realtime sessions take a capacity lease for the duration of the connection — under sustained load a session may be briefly queued rather than failing outright.

Batch API

OpenAI Batch-shaped: upload a JSONL file, create a batch job against /v1/chat/completions (or another supported endpoint), poll for completion, then fetch the output file.

file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
    input_file_id=file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
# poll client.batches.retrieve(batch.id) until status == "completed", then:
# client.files.content(batch.output_file_id)

Knowledge base stores

/v1/stores (create/list/get/delete) and /v1/stores/{store_id}/information (add/list/remove content) let you manage a knowledge base programmatically — the same underlying entity as a dashboard-created knowledge base. POST /v1/stores/{store_id}/query runs a similarity search and returns scored chunks.

curl -X POST https://api.v2.nairon.xyz/v1/stores \
  -H "Authorization: Bearer NAIRON_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Product Docs"}'

curl -X POST https://api.v2.nairon.xyz/v1/stores/STORE_ID/information \
  -H "Authorization: Bearer NAIRON_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Pricing page", "sourceType": "website", "source": "https://example.com/pricing"}'

curl -X POST https://api.v2.nairon.xyz/v1/stores/STORE_ID/query \
  -H "Authorization: Bearer NAIRON_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "What does the starter plan include?", "top_k": 6}'

Who am I

GET /v1/me returns which API key/project/organization resolved — useful for verifying a key before wiring it into an integration.

See the full platform-api reference for every endpoint and schema.