Chat API - Juryo

POST /api/v1/agent/chat runs your agent and answers in a single round trip. You send a message with a conversation id; Juryo keeps the conversation and replies. No session to create, no transcript to manage, no stream to parse unless you want the tokens as they arrive.

Base: https://chat.juryo.ai
Authentication: Authorization: Bearer YOUR_KEY — see Authentication and keys for which key to use and how to move to a new one

Measured on 17 August 2026 with a customer’s production agent: a complete reply in about 3 seconds (3.2 s on a cold start, 2.8–3.2 s warm), first token in about 2 seconds. The sessions API on the same agent: 6–11 s to a complete reply. Choose this endpoint when latency matters. Use the Sessions API instead when your integration needs the agent to ask you questions or approvals mid-conversation, long-running work, or cancel/clear/compact/reset controls — the comparison table there shows the two side by side.

The call

curl https://chat.juryo.ai/api/v1/agent/chat \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{"id": "conv-8841", "text": "Hi, I need information about a traffic accident claim."}'

{"id": "conv-8841", "text": "Hello, I'm the assistant at your law firm. Happy to help.\n\nWho do I have the pleasure of speaking with?"}

Send the next message with the same id — the agent remembers the conversation.

Field	Rules
`id`	Your conversation id, 1–200 characters. Same `id` = same conversation. Use one per end-user conversation (a ticket number, a chat id, a phone number hash).
`text`	The user’s message, 1–20,000 characters. Send either this or `message`, not both.
`message`	The message as a structured object, when you want to attach your own fields. Send either this or `text`, not both.

Juryo owns the transcript: send only the new message, never a list of messages.

Your own fields (metadata)

Attach your own key/value fields to a message with the structured message form. Use it to record where a conversation came from — a landing page, a campaign, your own reference — and to carry that through to the lead when it qualifies.

curl https://chat.juryo.ai/api/v1/agent/chat \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{
        "id": "conv-8841",
        "message": {
          "id": "msg-1",
          "role": "user",
          "parts": [{ "type": "text", "text": "Hi, I need information about a divorce." }],
          "metadata": { "source": "landing-divorce-en" }
        }
      }'

Field	Rules
`message.id`	Required. Your id for this message, unique within the conversation. A request without it is rejected with `400`.
`message.role`	Always `"user"`.
`message.parts`	The message content: `[{ "type": "text", "text": "…" }]`.
`metadata.source`	Optional. Up to 200 characters. The landing page or campaign this conversation came from — the field most integrations need.
any other key	Optional. Your own key names (up to 64 characters) with string values (up to 500 characters). Up to 20 keys in total.

Values must be strings — send "42", not 42, and flatten anything nested. A key you have not used before needs no change on our side. What happens to it:

It is stored on the conversation’s contact and shown in Juryo, so your team can see which page or campaign each conversation came from.
The agent can read it from the next message onwards. Fields are saved once the reply they arrived with has been produced, so a value sent on the first message is available to the agent from the second. If the agent must react to it on the very first message, put it in the message text as well.
Reading it is available to agents configured to use contact details; if yours does not appear to see the fields, ask us to check that agent’s setup.
When a conversation qualifies as a lead, it travels to the lead record and is included when Juryo pushes the lead back to your system.

Fields merge key by key across turns. Sending {"source": "landing-divorce-en"} on the first message and {"case_ref": "A-119"} on a later one leaves the contact with both — a key you stop sending is kept, not cleared. Send a key again with a new value to change it.

metadata only exists on the structured message form. The text shortcut has nowhere to put it, so switch to message when you need your own fields. Everything else — the same id, the response modes, the transcript — is unchanged.

Response modes

Pick with the Accept header.

`Accept`	You get	Use it for
(none) or `application/json`	`{"id", "text"}` once the reply is complete — the default	Server-to-server integrations
`text/plain`	The reply streamed as plain text, token by token	Chat UIs that render the reply as it arrives
`text/event-stream`	The event stream: standard Server-Sent Events, one JSON event per line — text deltas, tool activity, finish	Richer chat UIs that show progress and tool activity

Streaming

curl -N https://chat.juryo.ai/api/v1/agent/chat \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'accept: text/plain' \
  -H 'content-type: application/json' \
  -d '{"id": "conv-8841", "text": "What documents do you need from me?"}'

Read the body as it arrives; the connection closes when the reply is complete. Send the next message with the same id once it has.

Event stream

Standard Server-Sent Events: every line is data: followed by one JSON object with a type; the stream ends with data: [DONE]. Any SSE client in any language reads it — no library required.

curl -N https://chat.juryo.ai/api/v1/agent/chat \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'accept: text/event-stream' \
  -H 'content-type: application/json' \
  -d '{"id": "conv-8841", "text": "What documents do you need from me?"}'

data: {"type":"start"}
data: {"type":"start-step"}
data: {"type":"text-start","id":"0"}
data: {"type":"text-delta","id":"0","delta":"Hello,"}
data: {"type":"text-delta","id":"0","delta":" I'm the assistant"}
data: {"type":"text-end","id":"0"}
data: {"type":"finish-step"}
data: {"type":"finish","finishReason":"stop"}
data: [DONE]

`type`	Meaning
`start` / `finish`	The reply begins / ends. `finish` carries `finishReason` (`stop`, `length`, `tool-calls`, `error`).
`start-step` / `finish-step`	One model step; a reply that uses tools has several.
`text-start` / `text-delta` / `text-end`	A text segment: append each `delta` to the segment with that `id`.
`tool-input-start` / `tool-input-delta` / `tool-input-available`	The agent is calling a tool: `toolName`, `toolCallId`, then the complete `input`.
`tool-output-available`	The tool’s result (`output`) for that `toolCallId`.
`tool-output-error`	The tool failed (`errorText`).
`error`	The turn failed (`errorText`); the stream ends.
`[DONE]`	End of stream (not JSON).

Concatenate the text-deltas to get the same text the JSON mode returns. Ignore event types you don’t handle — new ones may appear.

AI SDK clients

The event stream is the AI SDK UI message stream protocol (x-vercel-ai-ui-message-stream: v1 on the response), so AI SDK clients work against this endpoint out of the box — no adapter:

import { DefaultChatTransport } from "ai";

const transport = new DefaultChatTransport({
  api: "https://chat.juryo.ai/api/v1/agent/chat",
  headers: {
    accept: "text/event-stream",
    authorization: `Bearer ${process.env.JURYO_API_KEY}`,
  },
  // Juryo keeps the transcript server-side — send only the new message.
  prepareSendMessagesRequest: ({ api, body, headers, id, messages }) => ({
    api,
    body: { ...body, id, message: messages.at(-1) },
    headers,
  }),
});

Pass the transport to useChat (React) or any other AI SDK chat client.

When a person is handling the conversation

When someone at the firm is handling the conversation, the agent does not answer. The API still stores the message and replies 200 with an empty text (an empty body in text/plain, a stream with no text in the event stream). Show nothing to the user; the firm replies from Juryo.

Authentication and keys

Every request carries one header:

Authorization: Bearer YOUR_KEY

A key is bound to one agent. The key decides which agent answers, so create one key per agent you want to expose. It is also bound to your firm — the key alone determines whose data the conversation belongs to, which is why nothing you send in the body can change that.

Which key to use

Juryo is moving to a new key system. Both kinds work on this endpoint, so you can switch on your own schedule.

Key	Where you create it	Use it for
Agent API key (current)	Settings → Integrations → Agent API keys → Create API key	New integrations, and anything you build from now on
`sk_live_…` secret key (legacy)	Settings → Integrations → Channels → API → Secret key	Existing server integrations. Still fully supported
`pk_live_…` publishable key (legacy)	The same channel screen	The website widget and the Sessions API. Accepted here for integrations that already use it — not the key to start a new one on

Agent API keys are the current system. You create one yourself: pick the agent it runs and give it a name (say, Website backend), and the key is shown once. One key per integration, each pointing at the agent that should answer it. The same key works on the agent runtime as well as this endpoint. The legacy keys live on the Channels → API screen instead, where the channel carries the agent rather than the key. That difference is why they are two separate sections.

Moving to a new key

Your old key keeps working while you switch. There is no cut-over window and no coordinated deploy:

Create an Agent API key for the integration and copy it — it is shown once.
Deploy it in place of the old key whenever you are ready.
Once it is live, delete the old key from the Channels → API screen.

If anything goes wrong at step 2, put the old key back — nothing about it changed when you created the new one.

Keep server keys on your server — never in a browser bundle or a mobile app. A key is stored as a hash and shown once, when it is created; if you lose it, issue a new one rather than trying to recover it. Rotating a legacy sk_live_… key from Regenerate on the channel screen invalidates the old one immediately, so deploy the replacement first. The publishable pk_live_… key is designed to appear in a web page and is not a secret.

Errors

Status	Meaning
`400`	Body is not JSON; `id` / `text` missing or too long; or `metadata` is the wrong shape — a non-string value, too many keys, or a key or value over its limit. Details in `issues`
`401`	Missing or unknown key
`403`	The key has no agent attached
`404`	The key’s agent is inactive
`429`	Rate limit exceeded — 60 turns per minute per key; wait the `Retry-After` header’s seconds and retry

In the streaming modes a failure mid-reply ends the stream early (the event stream sends an error event first); retry with the same id.

Good to know

Memory: the conversation is stored per agent and id, and replayed on every turn.
Your inbox: each turn is also recorded as a conversation in Juryo, against a contact created for that id — so an API conversation appears in the inbox alongside WhatsApp and widget ones. Any metadata you send is stored on that contact.
Tools: the agent’s connected integrations (calendar, email via Composio) and the HTTP tools your admin defined run inline. WhatsApp-specific tools (contact and pipeline actions) are not on this surface.
Model and reasoning are whatever you configured for the agent in Settings → Agents; the same configuration drives both APIs.
A turn may run up to 300 s when tools are involved; typical is 3–5 s.

​The call

​Your own fields (metadata)

​Response modes

​Streaming

​Event stream

​AI SDK clients

​When a person is handling the conversation

​Authentication and keys

​Which key to use

​Moving to a new key

​Errors

​Good to know

The call

Your own fields (metadata)

Response modes

Streaming

Event stream

AI SDK clients

When a person is handling the conversation

Authentication and keys

Which key to use

Moving to a new key

Errors

Good to know