> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/conversations-and-orchestration/rest-api-reference.md).

# REST API Reference — Conversations & Streaming

This page is the curated reference for the endpoints a client uses to **hold a conversation** with a deployed agent: start it, send messages (blocking or streamed), read it back, undo and redo, handle human-in-the-loop pauses, and end it. Every request and response below was captured from a running EDDI build.

The complete, generated API description — every store, every admin endpoint — is served by each instance at **`/openapi`** and is browsable at **`/q/swagger-ui`**. It always matches the build you are talking to, so use it for anything this page does not cover.

**Contents:** [Conventions](#conventions) · [Endpoint overview](#endpoint-overview) · [Starting](#starting-a-conversation) · [Sending a message](#sending-a-message) · [Streaming (SSE)](#streaming-a-turn-server-sent-events) · [Reading](#reading-a-conversation) · [Undo, redo, rerun](#undo-redo-and-rerun) · [Ending and cancelling](#ending-and-cancelling) · [Human-in-the-loop](#human-in-the-loop-approvals) · [Admin state reset](#resetting-a-stuck-conversation) · [Conversation store](#the-conversation-store) · [Errors](#errors)

## Conventions

* **Base URL.** The examples use `EDDI=http://localhost:7070`.
* **Authentication.** With OIDC enabled (`QUARKUS_OIDC_TENANT_ENABLED=true`), send `Authorization: Bearer <access token>`. The conversation endpoints accept the roles `eddi-admin`, `eddi-editor` and `eddi-user`; `cancel`, `resume`, `resume/stream`, `approval-status` and `pending-approvals` also accept `eddi-approver`, and the conversation store's reads also accept `eddi-approver` and `eddi-viewer`. There is no role hierarchy — a role is accepted only where it is listed. A non-admin can only touch conversations they own (the `userId` the conversation was started for). See [Security](https://docs.labs.ai/security-and-compliance/security.md).
* **Two ids.** A conversation is *started* on the agent (`/agents/{agentId}/start`); every later call addresses the **conversation** (`/agents/{conversationId}/…`). The same `/agents/` prefix is used for both.
* **Ids come back in `Location`.** A create answers `201` with an empty body and an `eddi://` URI in the `Location` header; the id is its last path segment.
* **Conversation states:** `READY`, `IN_PROGRESS`, `AWAITING_HUMAN`, `ENDED`, `ERROR`, `EXECUTION_INTERRUPTED`.

## Endpoint overview

| Method & path                                                  | Purpose                                                                                                                                                                                                                                                                 | Success                   |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `POST /agents/{agentId}/start`                                 | Start a conversation (optionally with a context map)                                                                                                                                                                                                                    | `201` + `Location`        |
| `POST /agents/{conversationId}`                                | Send a message (text or JSON), wait for the reply                                                                                                                                                                                                                       | `200` snapshot            |
| `POST /agents/{conversationId}/stream`                         | Send a message, receive the turn as Server-Sent Events                                                                                                                                                                                                                  | `200` `text/event-stream` |
| `POST /agents/{conversationId}/resume/stream`                  | Decide a paused conversation and receive the resumed turn as Server-Sent Events                                                                                                                                                                                         | `200` `text/event-stream` |
| `GET /agents/{conversationId}`                                 | Read the conversation                                                                                                                                                                                                                                                   | `200` snapshot            |
| `GET /agents/{conversationId}/status`                          | Read the conversation state                                                                                                                                                                                                                                             | `200` `"READY"`           |
| `GET /agents/{conversationId}/log`                             | Conversation history as chat messages                                                                                                                                                                                                                                   | `200`                     |
| `GET` / `POST /agents/{conversationId}/undo`                   | Is undo available? / undo the last turn                                                                                                                                                                                                                                 | `200`                     |
| `GET` / `POST /agents/{conversationId}/redo`                   | Is redo available? / redo                                                                                                                                                                                                                                               | `200`                     |
| `POST /agents/{conversationId}/rerun`                          | Re-execute the last turn                                                                                                                                                                                                                                                | `200` snapshot            |
| `POST /agents/{conversationId}/endConversation`                | End the conversation                                                                                                                                                                                                                                                    | `200`                     |
| `POST /agents/{conversationId}/cancel`                         | Cancel an executing or paused turn                                                                                                                                                                                                                                      | `200`                     |
| `POST /agents/{conversationId}/resume`                         | Submit a human decision for a paused turn                                                                                                                                                                                                                               | `200`                     |
| `GET /agents/{conversationId}/approval-status`                 | Pause details of a conversation                                                                                                                                                                                                                                         | `200`                     |
| `GET /agents/pending-approvals`                                | Conversations awaiting a human decision                                                                                                                                                                                                                                 | `200` list                |
| `GET /me/events`                                               | The caller's event stream: approvals, team progress, finished jobs, notifications — ids only (see [Your event stream](#your-event-stream))                                                                                                                              | `200` `text/event-stream` |
| `PATCH /agents/{conversationId}/state`                         | Admin: reset a stuck conversation to `READY` (a compare-and-set from the state it read: `409` when the state changed meanwhile or cannot be reset)                                                                                                                      | `200`                     |
| `GET /conversationstore/conversations`                         | List conversations (paged, filterable)                                                                                                                                                                                                                                  | `200` list                |
| `GET /conversationstore/conversations/search?q=`               | Search **my** conversations by title (paged; see [Searching my conversations](#searching-my-conversations))                                                                                                                                                             | `200` list                |
| `GET /conversationstore/conversations/simple/{conversationId}` | Read a conversation (same shape as `GET /agents/{id}`)                                                                                                                                                                                                                  | `200`                     |
| `GET /conversationstore/conversations/{conversationId}`        | Read the raw stored conversation memory. The `audit:*` step data (the compiled system prompt above all; `audit:token_usage` stays) is withheld unless the caller has `VIEW` on the agent — the same rule `approval-status?detail=full` and MCP `read_audit_trail` apply | `200`                     |
| `DELETE /conversationstore/conversations/{conversationId}`     | Delete a conversation                                                                                                                                                                                                                                                   | `204`                     |
| `GET /conversationstore/conversations/active/{agentId}`        | Open conversations of an agent (admin, editor; optional `agentVersion`)                                                                                                                                                                                                 | `200` list                |
| `POST /conversationstore/conversations/end`                    | End a list of conversations (admin, editor)                                                                                                                                                                                                                             | `200`                     |
| `POST /conversationstore/conversations/end-inactive`           | End conversations idle for `inactiveForDays` (admin; optional `agentId`, `dryRun`)                                                                                                                                                                                      | `200`                     |

The agent must be **deployed** to the environment you start in — see [Deployment management](https://docs.labs.ai/conversations-and-orchestration/deployment-management-of-agents.md).

## Starting a conversation

```bash
curl -i -X POST "$EDDI/agents/<AGENT_ID>/start?environment=production&userId=demo-user"
```

```
HTTP/1.1 201 Created
Location: eddi://ai.labs.conversation/conversationstore/conversations/6abf78ad892bd7bd6ee7b901
```

| Query parameter | Default      | Meaning                                                                                              |
| --------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
| `environment`   | `production` | The deployment environment: `production` or `test`                                                   |
| `userId`        | —            | The user the conversation belongs to. With OIDC on, the authenticated identity is used for ownership |

To start **with a context map**, send it as the JSON body — the body is the map itself, keyed by context name; there is no `input` field on this call:

```bash
curl -i -X POST "$EDDI/agents/<AGENT_ID>/start?environment=production&userId=demo-user" \
  -H "Content-Type: application/json" \
  -d '{ "userName": { "type": "string", "value": "Ada" } }'
```

The start turn runs the agent's workflows once, with the action `CONVERSATION_START`; whatever it outputs (a greeting, say) is in the conversation when you first read it. A context value is visible to templates only during the turn it was sent with, so a value needed later must be sent again or copied into a property — see [Passing context](https://docs.labs.ai/agent-configuration/passing-context-information.md).

Every context entry needs a `type` (`string`, `object`, `array` or `expressions`). An entry without one is refused with `400` and `{"error": {"code": "INVALID_CONTEXT", …}}` naming the key, on this call and on every `say`. The usual cause is wrapping the map in `{"context": {…}}` here, where the body is the map itself.

`404 Agent is not deployed or not ready` means no version of the agent is deployed and `READY` in that environment.

## Sending a message

**Retrying safely.** Send an `Idempotency-Key` (or `X-EDDI-Request-Id`; the former wins) header on `POST /agents/{conversationId}` and its `/stream` twin so a retried request does not run the turn twice. A duplicate of a turn still in flight answers `409` with `Retry-After`. The protection has limits: a failed turn is not remembered, and a completed turn is replayed only within `eddi.turns.idempotency.ttl-seconds` and while its step is among the conversation's latest 50. A retry outside those conditions runs the turn again and can repeat side-effecting tools. See [conversations.md](https://docs.labs.ai/conversations-and-orchestration/conversations.md#idempotent-turns).

The same path takes plain text or JSON.

```bash
curl -s -X POST "$EDDI/agents/<CONVERSATION_ID>" \
  -H "Content-Type: text/plain" --data 'hello'
```

```bash
curl -s -X POST "$EDDI/agents/<CONVERSATION_ID>" \
  -H "Content-Type: application/json" \
  -d '{ "input": "hello",
        "context": { "userName": { "type": "string", "value": "Ada" } } }'
```

The JSON body (`InputData`) has two fields: `input` (the message) and `context` (a map of name → `{ "type": …, "value": … }`, where `type` is `string`, `expressions`, `object` or `array`). Context keys the engine reserves for itself are removed from client-supplied context. Input longer than `eddi.conversations.max-input-chars` (default 200,000 characters) is refused with `413`, and so is a context entry of type `expressions` that is longer than `eddi.expressions.max-length` (32,768 characters) or nests deeper than `eddi.expressions.max-depth` (32 levels).

**Response** (`200`, abridged — `conversationSteps` is cut short):

```json
{
  "conversationId": "6abf78ad892bd7bd6ee7b901",
  "agentId": "6abf74a9892bd7bd6ee7b8f5",
  "agentVersion": 1,
  "userId": "demo-user",
  "environment": "production",
  "conversationState": "READY",
  "undoAvailable": true,
  "redoAvailable": false,
  "conversationOutputs": [
    {
      "input": "hello",
      "actions": ["welcome_action"],
      "output": [ { "type": "text", "text": "Hello Ada! How can I help you today?", "delay": 0 } ]
    }
  ],
  "conversationProperties": {},
  "conversationSteps": [
    { "conversationStep": [
        { "key": "input:initial", "value": "hello", "timestamp": 1790933170850, "originWorkflowId": "6abf74a8892bd7bd6ee7b8f4" },
        { "key": "actions", "value": ["welcome_action"], "timestamp": 1790933170853, "originWorkflowId": "6abf74a8892bd7bd6ee7b8f4" }
    ] }
  ]
}
```

`conversationOutputs[].output` is what to show the user; `quickReplies`, when the turn produced any, sits next to it. Query parameters, shared by this call, `/stream`, `/rerun` and `GET /agents/{conversationId}`:

| Parameter               | Default | Effect                                                                                                                                                                                                                                                      |
| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `returnDetailed`        | `false` | `true` returns the step's other memory entries too, except `audit:*`, `*:trace:*` and `*Error` keys, which are withheld (values are redacted). By default only the client-facing keys are returned: `input:initial`, `actions*`, `output*`, `quickReplies*` |
| `returnCurrentStepOnly` | `true`  | `false` returns all turns since the start                                                                                                                                                                                                                   |
| `returningFields`       | —       | Repeatable; restricts the snapshot to the named top-level fields                                                                                                                                                                                            |

Turns of one conversation are processed strictly in order. A message sent to a conversation that is `AWAITING_HUMAN` is refused with `409`, to an `ENDED` one with `410 Conversation has ended`.

## Streaming a turn (Server-Sent Events)

`POST /agents/{conversationId}/stream` takes the same JSON body as a JSON message and answers with `Content-Type: text/event-stream`. The turn runs exactly as it would on the blocking endpoint; the stream reports its progress and ends with a `done` event carrying the turn's state and outputs.

```bash
curl -s -N -X POST "$EDDI/agents/<CONVERSATION_ID>/stream" \
  -H "Content-Type: application/json" -H "Accept: text/event-stream" \
  -d '{ "input": "tell me something" }'
```

A captured turn of an agent whose workflow is parser → rules → LLM → output → templating (the model's text is shortened):

```
event:task_start
data: {"taskId":"eddi://ai.labs.parser","taskType":"expressions","index":0}

event:task_complete
data: {"taskId":"eddi://ai.labs.parser","taskType":"expressions","durationMs":7}

event:task_start
data: {"taskId":"eddi://ai.labs.behavior","taskType":"behavior_rules","index":1}

event:task_complete
data: {"taskId":"eddi://ai.labs.behavior","taskType":"behavior_rules","durationMs":0,"actions":["send_to_ai"]}

event:task_start
data: {"taskId":"eddi://ai.labs.llm","taskType":"langchain","index":2}

event:token
data: Here is something

event:token
data:  interesting.

event:task_complete
data: {"taskId":"eddi://ai.labs.llm","taskType":"langchain","durationMs":466,"actions":["send_to_ai"]}

event:task_start
data: {"taskId":"eddi://ai.labs.output","taskType":"output","index":3}

event:task_complete
data: {"taskId":"eddi://ai.labs.output","taskType":"output","durationMs":1,"actions":["send_to_ai"]}

event:task_start
data: {"taskId":"eddi://ai.labs.templating","taskType":"output","index":4}

event:task_complete
data: {"taskId":"eddi://ai.labs.templating","taskType":"output","durationMs":0,"actions":["send_to_ai"]}

event:done
data: {"conversationState":"READY","conversationOutputs":[{"input":"tell me something","actions":["send_to_ai"],"output":[{"type":"text","text":"Here is something interesting.","delay":0}]}]}
```

### Event contract

| Event                 | `data`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | When                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `task_start`          | `{"taskId","taskType","index"}`                                                                                                                                                                                                                                                                                                                                                                                                                                                          | A lifecycle task begins. `taskId` is the task's registered id (`eddi://ai.labs.behavior` for a step configured as `ai.labs.rules`, `eddi://ai.labs.httpcalls` for `ai.labs.apicalls`); `index` is its position in the turn                                                                                                                                                        |
| `task_complete`       | `{"taskId","taskType","durationMs"}` plus, when present, `actions` (the actions in memory after the task), `toolTrace` (the LLM task's tool calls, arguments redacted) and `confidence`                                                                                                                                                                                                                                                                                                  | A task finished                                                                                                                                                                                                                                                                                                                                                                   |
| `task_failed`         | `{"taskId","taskType","durationMs","errorType","error"}`                                                                                                                                                                                                                                                                                                                                                                                                                                 | A task threw. By default that stops the turn: the conversation goes to `ERROR` and the stream still ends with `done`, whose snapshot has `"conversationState":"ERROR"` and a `taskErrors` entry. An agent whose [memory policy](https://docs.labs.ai/architecture-and-concepts/memory-policy.md) continues on failure runs the next task instead                                  |
| `token`               | **Raw text**, not JSON                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | A chunk of model output, as the model streams it. Concatenate the chunks                                                                                                                                                                                                                                                                                                          |
| `tool_call`           | `{"tool","callId"}` plus `displayName` and `display` only for a tool the agent's [`toolDisplay`](https://docs.labs.ai/agent-configuration/langchain.md#showing-a-tool-call-to-a-watching-client-tooldisplay) names                                                                                                                                                                                                                                                                       | Sent right before a tool runs. **Never the arguments**, unless the designer allow-listed a few fields in `toolDisplay`                                                                                                                                                                                                                                                            |
| `tool_result`         | `{"tool","callId","status","durationMs","ok","summary"}` — `status` is `ok`, `error`, `not_executed` (refused or skipped before the tool ran: budget, quota, deadline, request changed after approval, or a result that reports `NOT_EXECUTED`) or `rejected` (a human declined it); `ok` is `status == "ok"`; `summary` is the start of the result, or of the refusal, redacted exactly like `task_complete`'s `toolTrace`, whitespace collapsed, at most 200 characters (may be empty) | Sent once for every `tool_call`, always after it in the same stream, whichever way the call ends — except a call cut off by a cancellation or a turn deadline interrupt, which ends the turn without its result; on a resume a gated call that is settled without running (declined, skipped) gets its `tool_call` immediately before its `tool_result`. **Never the raw result** |
| `hitl_resume`         | `{"pauseId","verdict"}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `/resume/stream` only. The decision was committed; sent once, before any event of the continued turn                                                                                                                                                                                                                                                                              |
| `approval_required`   | `{"pauseId","pauseType","callCount"}` — `pauseType` is `TOOL_CALL` or `RULE`; `callCount` the number of gated tool calls awaiting a decision (`0` for a rule pause)                                                                                                                                                                                                                                                                                                                      | The turn ends waiting for a human. Sent immediately before `done` on `/stream` and `/resume/stream`; pass `pauseId` back in the decision                                                                                                                                                                                                                                          |
| `cascade_step_start`  | `{"stepIndex","modelType","modelName","totalSteps"}`                                                                                                                                                                                                                                                                                                                                                                                                                                     | A [model cascade](https://docs.labs.ai/agent-configuration/model-cascade.md) step starts                                                                                                                                                                                                                                                                                          |
| `cascade_escalation`  | `{"fromStep","toStep","confidence","threshold","reason","durationMs"}`                                                                                                                                                                                                                                                                                                                                                                                                                   | The cascade escalates to the next model                                                                                                                                                                                                                                                                                                                                           |
| `llm_retry`           | `{"reason","attempt"}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | The LLM task asks the same model again after an unusable reply ([recovery policies](https://docs.labs.ai/agent-configuration/langchain.md#recovery-policies-retry-where-it-helps))                                                                                                                                                                                                |
| `guardrail_triggered` | `{"type","phase","action","taskId"}` — `phase` is `input` or `output`, `action` one of `block`, `redact`, `reprompt`, `warn`                                                                                                                                                                                                                                                                                                                                                             | An LLM task's [input or output guardrail](https://docs.labs.ai/agent-configuration/langchain.md#input-and-output-guardrails) fired. Sent before the answer; after a `block` the answer that follows is the block message                                                                                                                                                          |
| `done`                | A reduced snapshot: `conversationState`, `conversationOutputs`, and `hitlPausedAt` when the turn paused                                                                                                                                                                                                                                                                                                                                                                                  | **Terminal.** The turn completed. `GET /agents/{conversationId}` returns the full snapshot (properties, steps, undo and redo flags)                                                                                                                                                                                                                                               |
| `error`               | `{"message", …}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **Terminal.** The turn could not run or failed                                                                                                                                                                                                                                                                                                                                    |

> **`task_complete.toolTrace` carries arguments and results.** The `tool_call` and `tool_result` events are argument-free and result-free by design, but the `toolTrace` on an LLM task's `task_complete` lists every call with its arguments and results, redacted by the secret filter and not reduced further. A client that forwards these events to end users must drop `toolTrace` (and `done`'s `conversationOutputs` if it should not show them) and build its activity lines from `tool_call`/`tool_result` alone. The stored trace of a finished turn keeps each call's `callId`, so receipts can be rebuilt after a reload.

Rules for clients:

* **Exactly one terminal event** — `done` or `error` — ends every stream. Treat the `done` snapshot as authoritative for what to display; tokens are a preview. A turn in which a task failed still ends with `done`; check its `conversationState` (`ERROR`) and `taskErrors`. Captured with an LLM endpoint that was down:

  ```
  event:task_failed
  data: {"taskId":"eddi://ai.labs.llm","taskType":"langchain","durationMs":1196,"errorType":"transport","error":"Streaming chat failed: java.net.ConnectException"}

  event:done
  data: {"conversationState":"ERROR","conversationOutputs":[{"input":"hello","actions":["send_to_ai"],"taskErrors":[{"type":"errorDigest","taskId":"ai.labs.llm","taskType":"langchain","text":"Task 'eddi://ai.labs.llm' failed: Streaming chat failed:"}]}]}
  ```

  An `ERROR` conversation accepts the next message; an admin can also reset it (see [below](#resetting-a-stuck-conversation)).
* **Strip one space after `data:`.** Every `data:` line carries one delimiter space; a token's own leading space follows it (`data: interesting.` is the token `" interesting."`). A payload containing line breaks arrives as several `data:` lines, each padded the same way — join them with `\n`.
* **`token` only appears when the model streams.** A turn that runs no LLM task, or whose output comes from an output set, has no `token` events; the reply is in `done`.
* **An `error` before anything ran carries a `code`.** When the turn is refused up front — the cases the blocking endpoint answers with a status — the event is `{"message":"…","code":"…"}` with `code` one of `awaiting_approval`, `conversation_not_found`, `input_too_large`, `conversation_ended`, `agent_not_ready`, `agent_mismatch`, `quota_exceeded`, `quota_accounting_unavailable`, `processing_restricted` or `restriction_status_unavailable`. Branch on `code`, show `message`. Captured:

  ```
  event:error
  data: {"message":"Conversation has ended","code":"conversation_ended"}
  ```

  Any other failure is `{"message":"Internal server error","correlationId":"…"}`; the correlation id is in the server log next to the real cause. A started turn that then carries none of its events for `systemRuntime.agentTimeoutInSeconds` plus one keep-alive interval ends with `code` `turn_timeout` (the turn was abandoned and never returned); retry the message.
* **Ownership and input size are checked before the stream opens,** so those failures are plain `403` / `413` responses, not SSE events.
* **`/resume/stream` does not cancel on disconnect by default.** A resume is a deliberate human decision whose approved tool calls may already have run, so a dropped connection must not discard the turn and its trace. The resumed turn finishes and persists; read the conversation after reconnecting. `eddi.streaming.resume-cancel-on-client-disconnect` (default `false`) turns cancellation on for the resume stream only.
* **`POST /agents/{conversationId}/resume/stream`** takes the body and the `returnDetailed` / `returnCurrentStepOnly` / `returningFields` query flags of [`/resume`](https://docs.labs.ai/conversations-and-orchestration/hitl.md#reply-and-approver-on-resume), needs the same roles and runs the same checks, and shares the stream's event contract and keep-alive. A reply is a read, so it needs the owner-or-admin access `say` needs, as a `/resume` with reply flags does: an approver-only caller (`eddi-approver`, neither owner nor admin) gets `403` and the pause is not consumed - such callers use the plain `/resume`. Every refusal `/resume` has — `400` (malformed decision, bad `toolDecisions`, bad secret context), `403`, `404`, `409` (not `AWAITING_HUMAN`, agent not deployed, `pauseId` no longer current) and `503` (shutting down) — is the same plain HTTP error **before any event is written**. Once the decision is accepted the stream is `hitl_resume`, the resumed turn's events, then `approval_required` + `done` if it paused again or `done` if it settled. A resume that was accepted and then dropped (cancelled, ended, busy) ends with `error` and a `code` (`conversation_ended`, `awaiting_approval`, `conversation_busy` or `resume_dropped`); a failure, or losing the cluster lease, ends with `error` too, and so does a turn that went silent past `systemRuntime.agentTimeoutInSeconds` plus one keep-alive interval (`turn_timeout`).
* **Disconnecting cancels the turn** by default (`eddi.streaming.cancel-on-client-disconnect=true`; this governs `/stream` only, `/resume/stream` has its own switch, below). Set it to `false` to let the turn finish and persist when the client goes away; the reply is then there when the conversation is read again.
* **Silent stretches carry a keep-alive.** A model can work for a minute before its first token or tool call. When a stream has carried nothing for `eddi.streaming.keepalive-interval-seconds` (default `15`, `0` = off), EDDI writes an SSE comment line, `: keep-alive`, so a load balancer or proxy idle timeout (60 s on an AWS ALB) does not close the connection. SSE clients ignore comment lines; a hand-written parser must skip lines that start with `:`.

The Chat UI (`ui/chat`) and the Manager are reference consumers of this contract.

## Reading a conversation

```bash
curl -s "$EDDI/agents/<CONVERSATION_ID>?returnCurrentStepOnly=false"
curl -s "$EDDI/agents/<CONVERSATION_ID>/status"           # → "READY"
```

`GET /agents/{conversationId}` returns the same snapshot shape as a message reply, with the same query parameters. With `returnCurrentStepOnly=false` the first `conversationOutputs` entry is the start turn (`{"actions":["CONVERSATION_START"]}`).

`GET /agents/{conversationId}/log` returns the history as chat messages — the view an LLM gets:

```bash
curl -s "$EDDI/agents/<CONVERSATION_ID>/log?logSize=4"
```

```json
[
  { "role": "user", "content": [ { "type": "text", "value": "hello" } ] },
  { "role": "assistant", "content": [ { "type": "text", "value": "Hello ! How can I help you today?" } ] }
]
```

| Parameter    | Default | Effect                                      |
| ------------ | ------- | ------------------------------------------- |
| `outputType` | `json`  | `text` returns one line per message instead |
| `logSize`    | `-1`    | Number of entries; `-1` for all             |

## Undo, redo and rerun

```bash
curl -s "$EDDI/agents/<CONVERSATION_ID>/undo"              # → true   (text/plain)
curl -s -X POST "$EDDI/agents/<CONVERSATION_ID>/undo"      # → 200
curl -s "$EDDI/agents/<CONVERSATION_ID>/redo"              # → true
curl -s -X POST "$EDDI/agents/<CONVERSATION_ID>/redo"      # → 200; 409 when there is nothing to redo
```

Undo removes the last turn from the conversation and keeps it for redo; sending a new message discards the redo stack. The snapshot's `undoAvailable` and `redoAvailable` flags say the same as the two `GET`s.

`POST /agents/{conversationId}/rerun` executes the last turn again with its original input (for example after fixing the agent's configuration) and returns the new snapshot. It accepts the snapshot query parameters plus `language`.

## Ending and cancelling

```bash
curl -s -X POST "$EDDI/agents/<CONVERSATION_ID>/endConversation"    # → 200
curl -s "$EDDI/agents/<CONVERSATION_ID>/status"                     # → "ENDED"
```

An agent can also end the conversation itself with the action `CONVERSATION_END`. Afterwards every message is refused with `410 Conversation has ended`.

`POST /agents/{conversationId}/cancel` stops a turn that is executing or paused for approval. On an idle conversation it answers:

```
HTTP/1.1 409 Conflict
Nothing to cancel: conversation is neither awaiting approval nor executing. Use endConversation to close it.
```

## Human-in-the-loop approvals

When an agent's [HITL gate](https://docs.labs.ai/conversations-and-orchestration/hitl.md) pauses a turn, the conversation goes to `AWAITING_HUMAN` until someone decides.

```bash
curl -s "$EDDI/agents/pending-approvals?limit=50"
curl -s "$EDDI/agents/<CONVERSATION_ID>/approval-status"
curl -s -X POST "$EDDI/agents/<CONVERSATION_ID>/resume" \
  -H "Content-Type: application/json" \
  -d '{ "verdict": "APPROVED", "pauseId": "<pauseId from approval-status>", "note": "checked" }'
```

`approval-status` of a conversation that is not paused:

```json
{"conversationId":"6abf78ad892bd7bd6ee7b901","state":"READY","pausedAt":"","pauseId":"","pauseReason":"","timeoutPolicy":"","approvalTimeout":""}
```

The resume body is a decision: `verdict` (`APPROVED` or `REJECTED`, required), optional `note`, optional `pauseId` (send it — a decision for a pause that has since been replaced is refused with `409` instead of approving the wrong thing), and `toolDecisions` for per-tool-call gates. `?detail=full` on `approval-status` adds the full memory snapshot. `pending-approvals` takes `limit` (default 200, at most 1000).

| Response                                                                  | Meaning                                                                                 |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `400 Request body must include a 'verdict' field (APPROVED or REJECTED)`  | No verdict in the body                                                                  |
| `409 Conversation is not in a resumable state (current state: READY) — …` | Nothing is paused (already resumed, cancelled, timed out, or the agent is not deployed) |
| `409` naming `pauseId no longer current`                                  | The pause changed after the decision was made                                           |

### Your event stream

Instead of polling `pending-approvals`, a client can hold `GET /me/events` open: a Server-Sent Event stream that says, for the signed-in user only, when an approval they may decide is waiting (`approval.pending`) or was decided (`approval.decided`), and when a team discussion, a long job or a notification concerns them. Payloads carry ids and kinds, never content — fetch the details here. There is no replay: on (re)connect, refetch. One stream per tab, at most 8 per user by default (`429` past it); `401` without a sign-in.

```bash
curl -N -H "Authorization: Bearer $TOKEN" "$EDDI/me/events"
# event: ready
# data: {"v":1,"heartbeatSeconds":20}
#
# event: approval.pending
# data: {"id":"…","kind":"approval.pending","ts":1793961600000,"surface":"regular","conversationId":"6abf…","agentId":"66a0…"}
```

Every kind, who receives it, the limits and the cluster behaviour: [User Events](https://docs.labs.ai/conversations-and-orchestration/user-events.md).

## Resetting a stuck conversation

`PATCH /agents/{conversationId}/state?state=READY` (admin only) moves a conversation in `ERROR` or `EXECUTION_INTERRUPTED` back to `READY`. The endpoint refuses only `IN_PROGRESS` and `ENDED`, so it also resets an `AWAITING_HUMAN` conversation — prefer `cancel` for a pause. `READY` is the only accepted target, and the default when `state` is omitted:

| Situation                                                                | Response                                                                                  |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| Conversation in `ERROR` or `EXECUTION_INTERRUPTED` (or `AWAITING_HUMAN`) | `200 {"message":"State reset from ERROR to READY"}`                                       |
| Conversation already `READY`                                             | `200 {"message":"Conversation already in READY state"}`                                   |
| Any other `state` value                                                  | `400 {"error":"Only READY is supported as target state"}`                                 |
| Conversation `IN_PROGRESS`                                               | `409 {"error":"Cannot reset while conversation is IN_PROGRESS"}`                          |
| Conversation `ENDED`                                                     | `409 {"error":"Cannot reset an ENDED conversation"}`                                      |
| The state changed between the read and the reset                         | `409 {"error":"Conversation state changed while resetting it — read it again and retry"}` |
| Unknown conversation id                                                  | `404`                                                                                     |

## The conversation store

`/conversationstore/conversations` is the history view: listing, reading the stored document, deleting.

```bash
curl -s "$EDDI/conversationstore/conversations?agentId=<AGENT_ID>&limit=20&index=0"
```

```json
[
  {
    "resource": "eddi://ai.labs.conversation/conversationstore/conversations/6abf78ad892bd7bd6ee7b901",
    "createdOn": 1790933165895,
    "lastModifiedOn": 1790933188985,
    "deleted": false,
    "agentName": "",
    "userId": "demo-user",
    "agentResource": "eddi://ai.labs.agent/agentstore/agents/6abf74a9892bd7bd6ee7b8f5?version=1",
    "viewState": "UNSEEN",
    "conversationStepSize": 5,
    "environment": "production",
    "conversationState": "READY",
    "title": "What is the weather in Vienna?",
    "titleSource": "AUTO",
    "pinned": false
  }
]
```

`title` is the first user message that was not secret, truncated (`titleSource` `AUTO`), a model-written one for an agent with `titleGeneration` (`LLM`), or the owner's (`USER`); absent until the first such message.

| Parameter                 | Meaning                                                                                                                                                                                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index`, `limit`          | Page number and page size (default `0`, `20`). Page until a page comes back empty. A negative `index`, a `limit` above `eddi.rest.listing.max-limit` (default 1,000) or `index × limit` above 10,000 is refused with `400` — narrow the listing with a filter instead |
| `agentId`, `agentVersion` | Only this agent (version)                                                                                                                                                                                                                                             |
| `conversationState`       | Only conversations in this state                                                                                                                                                                                                                                      |
| `conversationId`          | One conversation                                                                                                                                                                                                                                                      |
| `viewState`               | `UNSEEN`, `SEEN`, …                                                                                                                                                                                                                                                   |
| `filter`                  | Free-text filter                                                                                                                                                                                                                                                      |
| `mine`                    | `true`: only the caller's own conversations (default `false`)                                                                                                                                                                                                         |
| `excludeGroupMembers`     | `true`: leave out the private conversations a group discussion started for its members — those whose descriptor records `groupConversationId`. Member conversations started before 6.7.0 record none and are still listed (since 6.7.0)                               |

Results are newest first. A non-admin sees only their own conversations, plus, with `agentId`, those of an agent they review; an admin sees everybody's.

`mine=true` narrows any caller, an admin included, to the conversations they own. Ask it whenever the listing picks a conversation to **continue**, as the Manager's chat panel does when it reopens an agent: an admin's listing otherwise holds every user's conversations, and the newest of them may be someone else's. The owner is an exact match on the descriptor's `userId`, so a conversation from before v5.1.6 that records no owner there is left out. With authorization disabled there is no caller to match and every conversation is listed.

A member conversation of a group discussion carries `groupConversationId` on its descriptor.

| Call                              | Notes                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET …/simple/{conversationId}`   | Same snapshot as `GET /agents/{conversationId}`, with the same query parameters                                                                                                                                                                                                                                                                                                                                                  |
| `GET …/{conversationId}`          | The stored conversation memory document, every step and key                                                                                                                                                                                                                                                                                                                                                                      |
| `PATCH …/{conversationId}`        | Owner (or admin): rename and/or pin, body `{"title": "…", "pinned": true}` (either field). `200` with the updated descriptor; `400` for an empty body or a blank or longer-than-200-character title; `404` for a deleted conversation. A title set here is never replaced by a generated one — see [Conversation titles](https://docs.labs.ai/agent-configuration/agent-config-authoring.md#conversation-titles-titlegeneration) |
| `DELETE …/{conversationId}`       | `204`. `?deletePermanently=true` removes the document instead of marking it deleted                                                                                                                                                                                                                                                                                                                                              |
| `DELETE …/?deleteOlderThanDays=N` | Admin only: permanently delete every **ended** conversation older than `N` days (`N ≥ 1`)                                                                                                                                                                                                                                                                                                                                        |
| `GET …/active/{agentId}`          | Admin or editor: open (not `ENDED`) conversations of an agent (`?agentVersion=` restricts it to one version), `[{"conversationId","agentId","agentVersion","conversationState","lastInteraction"}]`                                                                                                                                                                                                                              |
| `POST …/end`                      | Admin or editor: end the listed conversations. The body is a JSON array of objects of which only `conversationId` is read, so the `active` list can be sent back as it is; an array of plain id strings is refused with `400`. `?endReason=agent-version-retired` is the one accepted reason. The response lists the `ended`, `skipped` and `failed` ids, with status `500` if any failed                                        |

Every per-conversation call checks ownership, so a caller can neither read nor delete a conversation they do not own.

### Searching my conversations

```bash
curl -s "$EDDI/conversationstore/conversations/search?q=rome&index=0&limit=20"
```

Answers the same descriptors as the listing, newest first, for the conversations whose **title** contains `q`.

* **Only the caller's own conversations**, for every caller, an administrator included: this is "my conversations". (An administrator who needs everybody's uses the listing's `filter`.) The owner is part of the database query, as an exact match on the descriptor's `userId`, so another user's conversation is never read. With authorization disabled every conversation is searched, as the listing then shows every conversation. A conversation from before v5.1.6 that records no owner on its descriptor is not searched.
* `q` is literal text, not a pattern: `%`, `_`, `*` or `(` match themselves. It is case-insensitive, whitespace is collapsed the way titles are stored, and it must be 1 to 100 characters (`400` otherwise).
* `index`, `limit` page as in the listing (`index × limit` at most 10,000). A page can come back short, because a match whose conversation memory is gone is left out, so page until a page comes back empty.
* **Titles only.** A title never comes from a secret turn, and it lives on the conversation descriptor, which [GDPR erasure](https://docs.labs.ai/security-and-compliance/gdpr-compliance.md) deletes, so nothing the search can find outlives an erasure. Conversation *outputs* are not searched yet. Doing that safely needs more than a query: the outputs live in the conversation memory documents, not the descriptors, so they need their own index on both backends. They hold model and tool text that the turn-end scrub does not cover (it removes secret input and secret context, not what a tool echoed), so they would also need a decision on redaction. Both are open.
* MongoDB matches with an escaped, case-insensitive regex and PostgreSQL with an escaped `ILIKE`, both after the exact owner match narrows the rows to the caller's.

## Calling an API as the user: secret context

A context entry marked `"secret": true` lives for the request that carried it: the pipeline reads the live value, and it is replaced by `<secret context>` in everything stored when the turn ends. Send it with every message, and again in the `context` of `POST /agents/{conversationId}/resume` when a paused turn is approved:

```json
{ "input": "Show my open invoices",
  "context": { "userToken": { "type": "string", "value": "eyJ…", "secret": true } } }
```

An httpcall header written as `Bearer ${context:userToken}` sends it to the API — only from a secret entry, only in a header, only to the configuration's own host, and failing the call when it is missing. See [Per-turn credentials from secret context](https://docs.labs.ai/agent-configuration/httpcalls.md#per-turn-credentials-from-secret-context).

An agent whose tools are generated from an OpenAPI spec is managed with three admin endpoints, described under [the Platform Operator case study](https://docs.labs.ai/architecture-and-concepts/architecture.md#building-an-operator-agent-for-your-own-api):

| Method & path                                                 | Purpose                                                                                                    | Success                                                                    |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `POST /administration/agents/setup-api`                       | Create the agent (`apiAuth` may be `Bearer ${context:userToken}`)                                          | `201`                                                                      |
| `POST /administration/agents/setup-api` with `"dryRun": true` | Return what would be created; write nothing                                                                | `200`                                                                      |
| `POST /administration/agents/{agentId}/setup-api/sync`        | Regenerate the tools from a new spec as a compatible agent version; `"dryRun": true` reports the diff only | `200`; `400` naming each reference when a removed tool is still referenced |

## Errors

| Status | Body (examples)                                                                                                                                                                                                  | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `Request body must include a 'verdict' field …`                                                                                                                                                                  | Malformed request                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `401`  | —                                                                                                                                                                                                                | OIDC on and no or invalid token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `403`  | —                                                                                                                                                                                                                | Wrong role, not the conversation's owner, or processing restricted for this user ([GDPR](https://docs.labs.ai/security-and-compliance/gdpr-compliance.md))                                                                                                                                                                                                                                                                                                                                                                                                       |
| `404`  | `Agent is not deployed or not ready`                                                                                                                                                                             | No `READY` deployment of the agent in that environment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `404`  | `No conversation found! (conversationId=…)`; `Conversation not found.` from cancel, resume and approval-status                                                                                                   | Unknown conversation id                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `409`  | `Nothing to cancel: …`                                                                                                                                                                                           | The conversation's state does not allow the call — awaiting approval, nothing to redo, nothing to cancel                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `410`  | `Conversation has ended`                                                                                                                                                                                         | Message to an ended conversation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `413`  | —                                                                                                                                                                                                                | Input longer than `eddi.conversations.max-input-chars`, or a `context` entry of type `expressions` longer or nested deeper than `eddi.expressions.max-length` / `eddi.expressions.max-depth` allow                                                                                                                                                                                                                                                                                                                                                               |
| `422`  | `{"error": "agent_misconfigured", "message": "API call 'weather': header 'X-Api-Key' references ${vault:api-key} (no tenant given, so tenant 'default'), which could not be resolved: ...", "retryable": false}` | `POST /agents/{agentId}/start` only: the agent's own `CONVERSATION_START` turn hit a configuration it cannot run — a `${vault:…}` reference that names no secret in the tenant it is looked up in (or no vault is configured), or a secret sent to a host its [`allowedHosts`](https://docs.labs.ai/security-and-compliance/secrets-vault.md#destination-allow-list-allowedhosts) does not name. No conversation was created; fix the configuration rather than retrying. A server-side failure (the vault could not be read, the database failed) stays a `500` |
| `408`  | `caller_timed_out`                                                                                                                                                                                               | The caller's wait for the turn ran out (see [metrics.md](https://docs.labs.ai/deployment-and-infrastructure/metrics.md))                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `429`  | —                                                                                                                                                                                                                | A [tenant quota](https://docs.labs.ai/security-and-compliance/tenant-quotas.md) is exhausted                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `503`  | `capacity_exceeded` (with `Retry-After`)                                                                                                                                                                         | The node is at its in-flight turn limit (`eddi.conversation.max-in-flight-turns`), the per-conversation queue is full or the database pool is exhausted; retry after the delay                                                                                                                                                                                                                                                                                                                                                                                   |
| `503`  | —                                                                                                                                                                                                                | Quota accounting or the GDPR restriction status could not be read; retry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

For symptoms and fixes beyond the status code, see [Troubleshooting](https://docs.labs.ai/getting-started/troubleshooting.md).

## Related

* [Conversations](https://docs.labs.ai/conversations-and-orchestration/conversations.md) — how conversation state, memory and windowing work
* [Human-in-the-Loop](https://docs.labs.ai/conversations-and-orchestration/hitl.md) — pause configuration, timeouts, per-tool-call gates
* [User Events](https://docs.labs.ai/conversations-and-orchestration/user-events.md) — `GET /me/events`, the per-user event stream
* [Group Conversations](https://docs.labs.ai/conversations-and-orchestration/group-conversations.md) — the `/groups/{groupId}/conversations` API
* [OpenAI-compatible API](https://docs.labs.ai/protocols-and-integration/open-webui-integration.md) — `/v1/chat/completions` on top of the same engine
* [MCP Server](https://docs.labs.ai/protocols-and-integration/mcp-server.md) — the same operations as MCP tools
