Sessions API

The same pk_live_… key from your Widget (API) channel authorizes direct calls to the agent’s sessions API — durable conversations with an event stream, questions and approvals the agent can raise, and session controls. The web widget uses exactly this API under the hood.

Base: https://agents.juryo.ai
Authentication: Authorization: Bearer pk_live_… header

Which API?

Both use the same key. Pick by what your integration needs:

	Chat API	Sessions API (this page)
Shape	One `POST` per message, reply in the response	Create a session, send turns, read an event stream
Typical reply	~2–3 seconds	6–11 seconds
Memory	Yes — you pass a conversation id, we keep the history	Yes — durable session id
Streaming	Optional (plain text or event stream)	NDJSON event stream
Agent asks you a question / needs an approval	Not on this surface	Yes (`input.requested` + `inputResponses`)
Cancel / clear / compact / reset a conversation	No	Yes
Best for	Websites, forms, bots — anything conversational where speed matters	Integrations that need approvals, long-running work or session controls

If you don’t need the session controls, use the Chat API.

The key identifies your firm as the tenant. Any system presenting it can start conversations with your agent — the same way any visitor to your site can open the widget.

Breaking change (August 2026): the sessions API no longer uses continuation tokens. Starting a session no longer returns a continuationToken, and request bodies no longer accept one — a follow-up that still sends it fails with 400 Bad Request. Use the sessionId from the start response in the URL path of every follow-up, control, and stream call. See Migrating from continuation tokens below.

Routes

Method	Path	Purpose
`GET`	`/eve/v1/health`	Check the API is reachable (no auth required)
`POST`	`/eve/v1/session`	Start a session and send its first message
`POST`	`/eve/v1/session/{sessionId}`	Send a follow-up message
`GET`	`/eve/v1/session/{sessionId}/stream`	Stream session events as NDJSON
`POST`	`/eve/v1/session/{sessionId}/cancel`	Cancel the in-flight turn
`POST`	`/eve/v1/session/{sessionId}/clear`	Clear the session’s conversation history
`POST`	`/eve/v1/session/{sessionId}/compact`	Compact the session’s context
`POST`	`/eve/v1/session/{sessionId}/reset`	Retire the session permanently

The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.

Start a session

curl -X POST https://agents.juryo.ai/eve/v1/session \
  -H 'Authorization: Bearer pk_live_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{"message": "Hi, I need information about a claim."}'

{"ok": true, "sessionId": "wrun_A", "status": "accepted"}

sessionId is the session’s permanent handle. Store it — it goes in the URL path of every later call. The same id is also echoed in the x-eve-session-id response header.
status: "accepted" means the message was durably queued. The agent’s reply is not in this response — read it from the event stream.

Send a follow-up message

When the session is waiting for the next user message:

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A \
  -H 'Authorization: Bearer pk_live_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{"message": "It was a traffic accident."}'

A follow-up body accepts exactly one of message or inputResponses. Use inputResponses to answer a pending question or approval request the agent raised (an input.requested event on the stream):

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A \
  -H 'Authorization: Bearer pk_live_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{"inputResponses": [{"requestId": "req_A", "optionId": "approve"}]}'

Sending a message to an unknown or retired session ID returns 409 with {"code": "session_not_active", "error": "The session is no longer active.", "ok": false}. The route never creates a replacement session — start a new one explicitly with POST /eve/v1/session.

Stream the reply

The session emits newline-delimited JSON events (application/x-ndjson) while the agent works — one JSON object per line:

curl -N https://agents.juryo.ai/eve/v1/session/wrun_A/stream \
  -H 'Authorization: Bearer pk_live_YOUR_KEY'

{"type": "turn.started", ...}
{"type": "message.appended", "data": {"messageDelta": "It was ", ...}}
{"type": "message.completed", "data": {"message": "...", ...}}
{"type": "session.waiting", "data": {"wait": "next-user-message", ...}}

The events to build on:

message.completed — the agent’s full reply for that turn.
session.waiting — the turn is finished and the session is ready for your next follow-up.
input.requested — the agent is asking the caller a question or requesting an approval; answer it with inputResponses on the follow-up route.
turn.failed / session.failed — the turn or session errored; data.message carries the reason.

Clients that don’t render incremental text can ignore the *.appended events and rely on the *.completed ones.

For backwards compatibility, the session.waiting event still carries a data.continuationToken field. It is simply the session ID — ignore it and keep using the sessionId you already have.

Manage a session

All control routes are asynchronous: "accepted" means the request was durably queued, and the outcome is confirmed on the event stream. They never create sessions — an inactive session ID returns "no_active_session" (or "no_active_turn" for cancel). Cancel the in-flight turn (empty body, or pass the turnId from that turn’s stream events to scope it):

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A/cancel \
  -H 'Authorization: Bearer pk_live_YOUR_KEY'
# 202 {"ok": true, "sessionId": "wrun_A", "status": "accepted"}

Clear the conversation history without replacing the session (the agent forgets prior turns; configuration and durable state remain):

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A/clear \
  -H 'Authorization: Bearer pk_live_YOUR_KEY'

Compact a long conversation into a summary to free up context:

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A/compact \
  -H 'Authorization: Bearer pk_live_YOUR_KEY'

Reset retires the session permanently — the old ID can never accept another message:

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A/reset \
  -H 'Authorization: Bearer pk_live_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{"reason": "Start over"}'
# {"ok": true, "previousSessionId": "wrun_A", "status": "reset"}

Errors

Status	Meaning
`400`	Malformed body — for example both or neither of `message` / `inputResponses`, or a legacy `continuationToken` field
`401`	Missing or invalid `Authorization` bearer key
`409`	`session_not_active` — the session ID is unknown or retired; start a new session

Error bodies follow {"code": "...", "error": "...", "ok": false} with a stable code for programmatic handling.

Migrating from continuation tokens

Integrations built before August 2026 used a continuationToken returned by the start route. The mapping to the current API:

Before	Now
Start response body carried `continuationToken`	Start response body carries `sessionId` (also in the `x-eve-session-id` header)
Follow-up: `POST /eve/v1/session` with `{"continuationToken": "...", "message": "..."}`	Follow-up: `POST /eve/v1/session/{sessionId}` with `{"message": "..."}`
Session addressed by the token in the request body	Session addressed by `sessionId` in the URL path — the id never changes for the session’s whole life

In short: keep the sessionId from the start response, put it in the URL path, and remove continuationToken from every request body.

​Which API?

​Routes

​Start a session

​Send a follow-up message

​Stream the reply

​Manage a session

​Errors

​Migrating from continuation tokens

Which API?

Routes

Start a session

Send a follow-up message

Stream the reply

Manage a session

Errors

Migrating from continuation tokens