Your first conversation

This guide is for a developer wiring a server-side integration. You create a conversation for one end user, send a message, read the streamed answer, and fetch the stored transcript. It takes four requests.

Prerequisites

An API key. Either an organization API key from the portal (Settings, then API keys) or a scoped key (nxsk_v1_...) that carries conversations:use. The examples read the key from the NEXIO_API_KEY environment variable. See Authentication and access.
A Conversation instance with at least one published version. Create and publish one in the portal under Conversations, or see Versions and publish. The examples use the slug workspace-assistant.
An end_user value for the person your application is serving. The examples use u_dana_ortiz. Send the same value on every request for that person’s conversations.

Call these routes from your server. The API sends no CORS headers, and the key must never reach a browser.

Confirm the instance is published

List the instance’s released versions. For an instance you manage yourself, an empty list means turns will return 409 instance_not_published. An instance that follows another instance (a follower) runs the versions released on the instance it follows, so its own list can be empty while turns work.

curl https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/versions \
  -H "Authorization: Bearer $NEXIO_API_KEY"

import os
import requests

API = "https://api.usenexio.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]}

resp = requests.get(f"{API}/conversation-instances/workspace-assistant/versions", headers=HEADERS)
resp.raise_for_status()
print(resp.json())

const API = "https://api.usenexio.com/api/v1"
const HEADERS = { Authorization: `Bearer ${process.env.NEXIO_API_KEY}` }

const resp = await fetch(`${API}/conversation-instances/workspace-assistant/versions`, { headers: HEADERS })
if (!resp.ok) throw new Error(`versions: ${resp.status}`)
console.log(await resp.json())

Response 200:

{
  "versions": [
    {
      "version": 1,
      "config_hash": "4f1c9a7e2b8d3065",
      "changelog": "First release",
      "created_by": "user_01J8Q4Z7M2R6T9V3X5B1N0K8HD",
      "released_at": "2026-09-22T16:40:05Z"
    }
  ]
}

Create a conversation

Create a conversation for the end user. title and scope are optional. scope is a JSON object your application can use to remember what the conversation is about. It never grants access to anything.

curl -X POST https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user": "u_dana_ortiz",
    "title": "Getting started"
  }'

resp = requests.post(
    f"{API}/conversation-instances/workspace-assistant/conversations",
    headers=HEADERS,
    json={"end_user": "u_dana_ortiz", "title": "Getting started"},
)
resp.raise_for_status()
conversation = resp.json()
conversation_id = conversation["id"]

const created = await fetch(`${API}/conversation-instances/workspace-assistant/conversations`, {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({ end_user: "u_dana_ortiz", title: "Getting started" }),
})
if (!created.ok) throw new Error(`create: ${created.status}`)
const conversation = await created.json()
const conversationId: string = conversation.id

Response 201:

{
  "id": "9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93",
  "instance_id": "3b9d2f4e-8a1c-4e57-9f02-6c1d8e7a5b34",
  "end_user": "u_dana_ortiz",
  "title": "Getting started",
  "status": "active",
  "created_at": "2026-09-23T14:02:11.482913Z",
  "updated_at": "2026-09-23T14:02:11.482913Z"
}

Send a message and read the stream

Post a turn with message. The response is a Server-Sent Events stream: each frame is an event: line, a data: line of JSON, and a blank line. Read frames until a turn_end or error frame arrives. Set no client read timeout shorter than the 10-minute server limit on a segment.

curl -N -X POST https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations/9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93/turns \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "end_user": "u_dana_ortiz",
    "message": "What kinds of questions can you help me with?"
  }'

import json

def stream_turn(conversation_id: str, body: dict):
    """Yield (event, data) pairs until a terminal frame."""
    with requests.post(
        f"{API}/conversation-instances/workspace-assistant/conversations/{conversation_id}/turns",
        headers={**HEADERS, "Accept": "text/event-stream"},
        json=body,
        stream=True,
        timeout=(10, 660),
    ) as resp:
        if resp.status_code != 200:
            # Errors before the first frame use the JSON error envelope.
            raise RuntimeError(resp.json())
        event = None
        for line in resp.iter_lines(decode_unicode=True):
            if line.startswith("event: "):
                event = line[len("event: "):]
            elif line.startswith("data: "):
                data = json.loads(line[len("data: "):])
                yield event, data
                if event in ("turn_end", "error"):
                    return

answer = []
for event, data in stream_turn(conversation_id, {
    "end_user": "u_dana_ortiz",
    "message": "What kinds of questions can you help me with?",
}):
    if event == "conversation":
        turn_id = data["turn_id"]
    elif event == "text_delta":
        answer.append(data["text"])
    elif event == "turn_end":
        print("stop_reason:", data["stop_reason"])
    elif event == "error":
        print("turn failed:", data["code"], data["message"])
print("".join(answer))

async function* streamTurn(conversationId: string, body: Record<string, unknown>) {
  const resp = await fetch(
    `${API}/conversation-instances/workspace-assistant/conversations/${conversationId}/turns`,
    {
      method: "POST",
      headers: { ...HEADERS, "Content-Type": "application/json", Accept: "text/event-stream" },
      body: JSON.stringify(body),
    },
  )
  if (resp.status !== 200 || !resp.body) {
    // Errors before the first frame use the JSON error envelope.
    throw new Error(JSON.stringify(await resp.json()))
  }
  const reader = resp.body.getReader()
  const decoder = new TextDecoder()
  let buffer = ""
  while (true) {
    const { value, done } = await reader.read()
    if (done) return
    buffer += decoder.decode(value, { stream: true })
    let sep: number
    while ((sep = buffer.indexOf("\n\n")) !== -1) {
      const raw = buffer.slice(0, sep)
      buffer = buffer.slice(sep + 2)
      let event = ""
      let data = ""
      for (const line of raw.split("\n")) {
        if (line.startsWith("event: ")) event = line.slice(7)
        else if (line.startsWith("data: ")) data = line.slice(6)
      }
      const payload = JSON.parse(data)
      yield { event, payload }
      if (event === "turn_end" || event === "error") return
    }
  }
}

let answer = ""
for await (const { event, payload } of streamTurn(conversationId, {
  end_user: "u_dana_ortiz",
  message: "What kinds of questions can you help me with?",
})) {
  if (event === "text_delta") answer += payload.text
  if (event === "turn_end") console.log("stop_reason:", payload.stop_reason)
  if (event === "error") console.error("turn failed:", payload.code, payload.message)
}
console.log(answer)

The stream for this message:

event: conversation
data: {"type":"conversation","conversation_id":"9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93","turn_id":"5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75","user_message_id":"c7d1e5a3-2f84-4b6c-9e0a-1b3d5f7a9c28"}

event: text_delta
data: {"type":"text_delta","text":"I can answer questions about this workspace: "}

event: text_delta
data: {"type":"text_delta","text":"its engines, recent runs and their status, and the data it can read."}

event: turn_end
data: {"type":"turn_end","stop_reason":"end_turn","usage":{"input_tokens":1840,"output_tokens":31,"total_tokens":1871,"cached_input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0}}

The first frame is conversation. It carries the turn_id and the id of the user message the turn stored. text_delta frames carry the answer in pieces. The stream ends with exactly one turn_end or error frame. The answer text depends on the instance’s system prompt and tools; the frame shapes do not. Every frame type is described on Turns and streaming.If the connection drops, the turn still runs to completion on the server and is stored. Fetch the conversation to see the result.

Read the stored conversation

Fetch the conversation with the same end_user. The response holds the most recent 500 messages of the branch the conversation serves, oldest first.

curl "https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations/9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93?end_user=u_dana_ortiz" \
  -H "Authorization: Bearer $NEXIO_API_KEY"

resp = requests.get(
    f"{API}/conversation-instances/workspace-assistant/conversations/{conversation_id}",
    headers=HEADERS,
    params={"end_user": "u_dana_ortiz"},
)
resp.raise_for_status()
for message in resp.json()["messages"]:
    print(message["role"], message["content"])

const detail = await fetch(
  `${API}/conversation-instances/workspace-assistant/conversations/${conversationId}?end_user=u_dana_ortiz`,
  { headers: HEADERS },
).then((r) => r.json())
for (const message of detail.messages) console.log(message.role, message.content)

Response 200:

{
  "conversation": {
    "id": "9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93",
    "instance_id": "3b9d2f4e-8a1c-4e57-9f02-6c1d8e7a5b34",
    "end_user": "u_dana_ortiz",
    "title": "Getting started",
    "status": "active",
    "created_at": "2026-09-23T14:02:11.482913Z",
    "updated_at": "2026-09-23T14:02:19.207551Z"
  },
  "messages": [
    {
      "id": "c7d1e5a3-2f84-4b6c-9e0a-1b3d5f7a9c28",
      "role": "user",
      "content": [{ "type": "text", "text": "What kinds of questions can you help me with?" }],
      "turn_id": "5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75",
      "config_version_hash": "4f1c9a7e2b8d3065",
      "created_at": "2026-09-23T14:02:13.118402Z",
      "parent_message_id": null
    },
    {
      "id": "e2b8f4c6-7a1d-4c3e-8f95-0d6a2c4e8b17",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "I can answer questions about this workspace: its engines, recent runs and their status, and the data it can read."
        }
      ],
      "turn_id": "5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75",
      "config_version_hash": "4f1c9a7e2b8d3065",
      "created_at": "2026-09-23T14:02:19.203117Z",
      "parent_message_id": "c7d1e5a3-2f84-4b6c-9e0a-1b3d5f7a9c28"
    }
  ],
  "truncated": false
}

config_version_hash records which released config answered. parent_message_id links messages on their branch; see Branching.

What to build next

Goal	Page
Handle every frame, stop reason, and mid-stream error	Turns and streaming
Let the assistant call your own code, with approval for writes	Client tools and confirmations
Attach PDFs, spreadsheets, emails, or folders to a message	Attachments
Let users revise a sent message	Branching
Collect ratings and turn them into regression tests	Evaluation
Hand a transcript to a reviewer	Export and retention

Common errors

Status and code	Cause	Fix
`400 invalid_request` “end_user is required.”	The turn body has no `end_user`.	Send `end_user` on every turn and every conversation request.
`400 invalid_request` “depth is no longer supported”	The body sends the retired `depth` field.	Remove `depth`. Every turn uses the platform’s one model.
`403 insufficient_capability`	A scoped key without `conversations:use`.	Ask Nexio to add the capability, or use a key that has it.
`403 instance_archived`	The instance is archived.	Reactivate it in the portal or with `PATCH` and `status: active`.
`404 instance_not_found`	The slug does not exist in your org.	Check the slug with the instance list.
`404 conversation_not_found`	Wrong conversation id, or a different `end_user` or environment than the one that created it.	Use the same key environment and `end_user` that created the conversation.
`409 instance_not_published`	The instance has no published version.	Publish a version first.
`409 turn_in_progress`	Another turn segment is still running on this conversation.	Wait for the running stream to end, then send.
`409 pending_turn`	The last turn paused for a client tool or a confirmation.	Resolve it first. See Client tools and confirmations.
`503 converse_unavailable`	Conversations are not enabled in this deployment.	Contact Nexio.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Your first conversation

Prerequisites

What to build next

Common errors

​Prerequisites

​What to build next

​Common errors

Prerequisites

What to build next

Common errors