Sessions and messages

A session is one conversation of one end user. Each message the user sends starts a task — the assistant's answer — which streams on the session's event stream and is kept in the session's message list. All of these calls use the end user's token.

Create a session

curl -s "$NEWEYES_API_BASE/v1/sessions" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"output_format": "a2ui", "text": "What can I cook with leeks and potatoes?"}'

• output_format fixes the form of the session's replies for its whole life:
  • a2ui (the default) — the reply is UI data your app renders with an A2UI renderer, with the words the reply says outside that UI as plain text. See A2UI replies.
  • markdown — the reply is formatted Markdown text.
• capabilities or exclude_capabilities choose what the assistant may use in the session, also for its whole life: only the ones listed, or all but those. Send neither to open all of them. See Choosing a session's capabilities.
• text is optional. With it, the first task starts right away and the response carries its task_id and last_event_id. Without it, you get an empty session, which needs no balance.
• attachments go with text, as in a later message (below).

The response is the session:

Field	Meaning
id	The session's identifier.
type	text for a typed conversation, realtime for a voice call.
status	created, queued, running, completed, failed, stopped or timeout.
output_format	a2ui or markdown.
brief_status	Whether a voice session's brief is ready.
created_at, ended_at	When it started; when it ended, or null while it is open.
capabilities	What the assistant may use in the session.
task_id, last_event_id	Only on creation: the first task, and where it begins on the event stream.

Send a message

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/messages" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"text": "Make it vegetarian."}'

{ "object": "task", "task_id": "exec-5a2c…", "session_id": "9c1e…", "last_event_id": "1760860912345-0" }

• text is what the user says: 1 to 32,000 characters.
• The answer is 202 Accepted with the task it started. Follow it on the event stream from last_event_id, or send "stream": true to receive it on this request instead — see Event streams.
• One task at a time. While a task is running, a new message is refused with 409 session_busy. Wait for the task's end frame, or stop it first.
• A voice session does not take typed messages (409 session_not_taskable).
• Starting a task needs a spendable balance (429 insufficient_credits otherwise).

Attach media

A message can carry up to 10 images or videos:

{
  "text": "Which of these two rooms gets more light?",
  "attachments": [
    { "file_id": "3d0f…" },
    { "file_data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…" }
  ]
}

Each attachment is exactly one of:

• file_id — a file the user uploaded with POST /v1/files. Use this for anything large, such as a video.
• file_data — the file's bytes as base64, inline, up to 10 MB. A data:…;base64, prefix is accepted.

Audio is not a message attachment (422 unsupported_media_type); transcribe it with POST /v1/audio/transcriptions and send the text instead.

Reply to a UI action

In an a2ui session, a message the user sends by acting on the UI — tapping a button, submitting a form — carries the renderer's action in a2ui_action. See A2UI replies.

Stop a task

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/stop" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN"

The running task ends with a task.stopped frame, which carries what the reply had said so far. The answer names the stopped task's task_id, or null when no task was running.

Read the conversation

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/messages?limit=50" \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN"

The list is in conversation order and paginated. Each item has a type:

type	What it is
user_message	What the user sent: content, and its attachments.
assistant_message	A reply: its content, its attachments (images, videos, audio and files it made), its suggestions, and the task_id of the task that wrote it.
status_update	A notice about a task, such as its failure, with an error.
activity	A step the assistant took. Listed only with verbose=true.

• An attachment's url is a download link signed afresh on every read; it expires at its expires_at (one hour). Read the list again for a new link.
• Older messages are archived over time, and archiving can change a message's id. Match a reply by its task_id, not by its id. A cursor keeps its place across archiving.
• A voice session lists its transcript.

List, read and delete sessions

Call	Does
GET /v1/sessions	The user's sessions, newest first. Deleted ones are not listed.
GET /v1/sessions/{session_id}	One session.
DELETE /v1/sessions/{session_id}	Deletes it: it no longer appears in lists or reads.

A voice session cannot be deleted while its call is still connected (409 call_in_progress). If cleaning up the session's stored data fails, nothing is deleted and the call answers 503: retry it.

A session is visible only to the end user who owns it; another user's session reads as 404 session_not_found.