Appearance
AI Engine — Agentic chat history
The API stores the chats of the in-app assistant (Agentic UI) that the client chose to keep. The client (the webapp BFF and widget, built on the FE side) decides what to save and when to summarize. prepare and the gateway never read this store. This page is the handoff to the FE side: the API contract of /ai/agentic/conversations and of summary turns, and the rules the client must follow.
Source: service/api/src/modules/ai/ — services/agentic-history.service.ts, controllers/agentic-history.controller.ts, migration 105-ai-agentic-history. Summary turns: services/agentic-turn.service.ts, services/agentic-gateway.ts. The rest of Agentic UI (settings, prepare, gateway, turns, quota): AI Engine §Agentic UI.
Who can call
- Every route takes the user's own token. There is no service-token or "on behalf of" path.
- The caller must have app access (or be admin) and must not be in an impersonation session.
- A sub-token needs the matching scope:
read(GET),create(POST),update(PATCH),createandupdate(PUT),delete(DELETE and purge). - The
aimodule permission is not needed. - Every read and write is limited to the caller's own rows, admin included. An admin sees only their own conversations, and can purge but not read another user's.
Rules for the client
These are rules for the client side. The API does not and cannot enforce them; a client that breaks them stores data the design says must not exist.
- Save on the user's token only. Call every route with the signed-in user's own token, never a shared app or service-account token. Otherwise every user's history lands on one account.
- Never store tool output,
errorText, image bytes ordata:URLs, keys or tokens, or decrypted turn content (app system prompt, knowledge). See What a client must never store for what to store instead. - Mark an incomplete tool part as interrupted before you save it, so a restore never looks like a call still running.
- Restore runs no tool. Showing a saved conversation only renders it. A restored GenUI program renders with the viewer's current rights and the URL safety gate; a restored mutation button asks for confirmation like a live one; a restored
propose_patchis inert. - Put the summary in as data. When a saved
summarygoes back into a later prompt, wrap it as an untrusted data block, escape<, and keep it at most 4 000 characters. Never put it in as an instruction: it is derived from user text, so it can carry an injection from an earlier session. - Show a way out at a cap. On 409
AGENTIC_HISTORY_LIMIT, keep the chat going unsaved and tell the user to start a new chat or delete one. On 409AGENTIC_HISTORY_OFF, keep the chat going unsaved. A save error must never fail or block a chat turn. - Regenerate with a truncate. Before you save a regenerated answer, delete from the old one (
DELETE …/messages?from=), or the store keeps both. - Summarize only on the engine path (an app is selected), through a summary turn, streamed.
Conventions
- Every response is wrapped in
{ data }; the two lists addmeta. - Timestamps are ISO 8601 UTC strings, from the database clock.
- Another user's conversation answers exactly like an unknown id: 404.
ts
interface Conversation {
id: string // uuid, server generated
title: string | null
app_id: string | null // app selected when it was created; null on the env path. Set by the server only.
message_count: number
date_created: string
date_updated: string // moves on every message write, truncate and PATCH
}
interface ConversationDetail extends Conversation {
summary: string | null
summary_seq: number | null // last message seq the summary covers
}
interface Message {
id: string // the client UIMessage.id
role: 'user' | 'assistant'
parts: unknown[] // returned exactly as sent
seq: number // 1-based position in the conversation
date_created: string
}Routes
| Method + path | Request | Response |
|---|---|---|
GET /ai/agentic/conversations | ?limit=1–100 (20), ?offset (0) | 200 { data: Conversation[], meta: { total } } |
POST /ai/agentic/conversations | { title? } | 201 { data: ConversationDetail } |
GET /ai/agentic/conversations/:id | 200 { data: ConversationDetail } | |
PATCH /ai/agentic/conversations/:id | { title?, summary?, summary_seq? } | 200 { data: ConversationDetail } |
DELETE /ai/agentic/conversations/:id | 204 | |
GET /ai/agentic/conversations/:id/messages | ?limit=1–500 (200), ?after or ?before | 200 { data: Message[], meta: { message_count } } |
PUT /ai/agentic/conversations/:id/messages | { messages: [{ id, role, parts }] }, 1–8 | 200 { data: Message[] } |
DELETE /ai/agentic/conversations/:id/messages?from=<id> | 200 { data: { deleted } } | |
POST /ai/agentic/history/purge | { user_id?, before? }, admin only | 200 { data: { conversations, messages } } |
List conversations
Offset paging, newest date_updated first (id breaks ties). A conversation moves to the top when it is written to, so a row can show twice or be skipped between two page loads: reload page 1 after a write. A user has 200 conversations at most.
http
GET /ai/agentic/conversations?limit=20&offset=0
200 { "data": [
{ "id": "7d1c2f0e-…", "title": "Refund policy", "app_id": "3b9a…", "message_count": 4,
"date_created": "2026-11-03T07:12:04.000Z", "date_updated": "2026-11-03T07:15:31.000Z" }
], "meta": { "total": 1 } }The list leaves summary out; read one conversation to get it.
Create a conversation
title is optional, up to 255 characters. The server sets app_id to the app selected at that moment.
http
POST /ai/agentic/conversations
{ "title": "Refund policy" }
201 { "data": { "id": "7d1c2f0e-…", "title": "Refund policy", "app_id": "3b9a…", "message_count": 0,
"date_created": "2026-11-03T07:12:04.000Z", "date_updated": "2026-11-03T07:12:04.000Z",
"summary": null, "summary_seq": null } }Read a conversation
http
GET /ai/agentic/conversations/7d1c2f0e-…
200 { "data": { "id": "7d1c2f0e-…", "title": "Refund policy", "app_id": "3b9a…", "message_count": 4,
"date_created": "…", "date_updated": "…",
"summary": "The user asked about refunds; the window is 30 days.", "summary_seq": 2 } }Update a conversation
At least one field. null clears it. summary is at most 32 KiB. summary_seq must be the seq of an existing message, or null.
http
PATCH /ai/agentic/conversations/7d1c2f0e-…
{ "summary": "The user asked about refunds; the window is 30 days.", "summary_seq": 2 }
200 { "data": { …ConversationDetail } }Delete a conversation
Its messages go with it.
http
DELETE /ai/agentic/conversations/7d1c2f0e-…
204Read messages
Always returned in ascending seq. seq runs from 1 to message_count with no gap, because only a tail is ever deleted.
- No cursor: the newest
limitmessages. Use it to open a conversation. Withlimit=500, the cap, one call loads all of it. ?before=<seq>: thelimitmessages just beforeseq. To scroll back, pass theseqof the first message you hold. More remain while that firstseqis above 1.?after=<seq>: the firstlimitmessages afterseq. To build the model context, passsummary_seqand send the summary plus these messages.afterandbeforetogether are 400.limit,offset,afterandbeforemust be plain digits.
http
GET /ai/agentic/conversations/7d1c2f0e-…/messages?after=2&limit=200
200 { "data": [
{ "id": "Hk2nq81LpX0aZ3sT", "role": "user", "parts": [{ "type": "text", "text": "And for gifts?" }],
"seq": 3, "date_created": "2026-11-03T07:15:30.000Z" },
{ "id": "Qw7rT0bnL3xYk2Ps", "role": "assistant", "parts": [{ "type": "text", "text": "Gifts: 60 days." }],
"seq": 4, "date_created": "2026-11-03T07:15:31.000Z" }
], "meta": { "message_count": 4 } }Save messages (upsert)
One request writes 1–8 messages, in order, in one transaction that locks the conversation, all or nothing:
- an
idalready in this conversation keeps itsseqanddate_created, and itspartsis replaced. The sameidwith anotherroleis 409AGENTIC_MESSAGE_ROLE_CONFLICT, and nothing of the request is written; - a new
idis appended with the nextseq; - the same
idin another conversation is a different message; message_count, the stored size anddate_updatedchange in the same transaction.
Use one PUT per chat request: the new user message (first round only) and the assistant message. Later tool rounds of the same turn PUT the same assistant id again with its new parts. The answer holds the messages of this request only, in seq order.
http
PUT /ai/agentic/conversations/7d1c2f0e-…/messages
{ "messages": [
{ "id": "Hk2nq81LpX0aZ3sT", "role": "user", "parts": [{ "type": "text", "text": "Refund policy?" }] },
{ "id": "Qw7rT0bnL3xYk2Ps", "role": "assistant", "parts": [{ "type": "text", "text": "30 days." }] }
] }
200 { "data": [
{ "id": "Hk2nq81LpX0aZ3sT", "role": "user", "parts": [{ "type": "text", "text": "Refund policy?" }],
"seq": 1, "date_created": "2026-11-03T07:12:04.000Z" },
{ "id": "Qw7rT0bnL3xYk2Ps", "role": "assistant", "parts": [{ "type": "text", "text": "30 days." }],
"seq": 2, "date_created": "2026-11-03T07:12:04.000Z" }
] }Truncate for regenerate
regenerate() replaces the last assistant message with a new id. Without a truncate, the store would keep both answers.
- Delete from the old assistant message:
DELETE …/messages?from=<old id>. - PUT the new assistant message. It takes the freed
seq.
The truncate deletes that message and every later one, in the same kind of transaction:
message_countbecomesseq(from) − 1;- if
summary_seqis at or afterseq(from),summaryandsummary_seqare cleared, because the summary covered a deleted message; - an
idnot in this conversation is 404AGENTIC_MESSAGE_NOT_FOUND; nofromis 400.
http
DELETE /ai/agentic/conversations/7d1c2f0e-…/messages?from=Qw7rT0bnL3xYk2Ps
200 { "data": { "deleted": 1 } }Admin purge
Deletes conversations of any user without reading them.
- Admin only, not in an impersonation session. A sub-token needs the
deletescope. - Body
{ "user_id": "<uuid>" },{ "before": "<ISO date>" }(compared withdate_updated), or both. At least one is required;{ "before": <now> }purges everything. - The answer is counts only, never rows.
- One
odp_activityrow (action: purge) records the filter and the counts, never content.
http
POST /ai/agentic/history/purge
{ "user_id": "5f0d…", "before": "2026-08-01T00:00:00Z" }
200 { "data": { "conversations": 3, "messages": 41 } }What is stored in parts
The API checks only the outline:
idmatches^[A-Za-z0-9_-]{1,128}$and is case-sensitive (aB1andAb1are two messages);roleisuserorassistant. A system message is never stored;partsis an array of at most 200 objects, each with a stringtype. Nothing deeper is checked, so a new AI SDK part type needs no API change;- a part whose
urlordatais adata:URL is 400.
What a client must never store
Client rule. The API cannot check these; the client must keep them out:
| Never store | Store instead |
|---|---|
| Tool output (the result of a tool call) | Tool name, an args summary of at most 200 characters, the state, and for an approval the decision |
errorText of a tool part | The state only |
Image bytes or a data: URL | The text [image sent: <name>] |
| Keys, tokens, passwords | Nothing |
Decrypted turn content (the app system prompt, knowledge from prepare) | Nothing: it never reaches the client |
| Reasoning parts | Nothing |
UIMessage.metadata | Nothing |
Why: a tool output was read under the user's rights at that moment. Stored, it stays readable after those rights change.
Client rule: two inputs are kept, because the chat cannot be shown without them:
- the
ui_presentprogram. On restore it renders with the viewer's current rights and the URL safety gate; - the
dashboard.propose_patchpatch, shown inert.
An unfinished tool part is stored as interrupted, and restoring runs nothing (client rules 3 and 4).
Caps
| Cap | Value | On reach |
|---|---|---|
One message (serialized parts) | 256 KiB | 413 AGENTIC_MESSAGE_TOO_LARGE |
Request body of PUT …/messages | 2 MiB | 413 PAYLOAD_TOO_LARGE |
| Messages per conversation | 500 | 409 AGENTIC_HISTORY_LIMIT, extensions.limit: "messages" |
| Bytes per conversation | 8 MiB | 409 AGENTIC_HISTORY_LIMIT, limit: "conversation_bytes" |
| Conversations per user | 200 | 409 AGENTIC_HISTORY_LIMIT, limit: "conversations" |
| Bytes per user | 64 MiB | 409 AGENTIC_HISTORY_LIMIT, limit: "user_bytes" |
title | 255 characters | 400 |
summary | 32 KiB | 400 |
The API refuses at a cap and never drops old data on its own. Two writes in two conversations at the same time can pass a per-user cap by one write. What the client shows on a 409: client rule 6.
Assistant off
With enabled: false saved in the Agentic settings, create and upsert are 409 AGENTIC_HISTORY_OFF. Reads, PATCH, truncate and delete still work, so a user can remove what was kept. The API never reads the webapp's ODP_AGENT_ENABLED; with that kill switch on, the client must write nothing.
Retention
A conversation is deleted once its date_updated is older than history_retention_days (default 90).
- Admins set it with
PATCH /ai/agentic/settings { "history_retention_days": 30 }(ai.manage): an integer from 1 to 3650, ornullfor the default.GET /ai/agentic/configreturns it. - On the first save,
enabledis required as for any setting, because the first row turns the assistant on or off. - The schedule
ai-agentic-history-prune(17 * * * *) deletes 500 at a time and is safe on several instances. - Deleting a user deletes their conversations and messages.
- A user deletes a conversation at any time with
DELETE …/conversations/:id.
Errors
Every error, schema failures included, has this shape:
json
{ "errors": [{ "message": "Chat history limit reached: messages", "extensions": { "code": "AGENTIC_HISTORY_LIMIT", "limit": "messages" } }] }| Status | Code | When |
|---|---|---|
| 400 | INVALID_PAYLOAD | Schema, a parts rule, a bad query integer, both after and before, summary_seq above the last message, summary or title too long, purge with no filter |
| 401 | INVALID_CREDENTIALS | No user |
| 403 | FORBIDDEN | No app access, an impersonation session, a sub-token without the scope, purge by a non-admin |
| 404 | AGENTIC_CONVERSATION_NOT_FOUND | Unknown id, or another user's |
| 404 | AGENTIC_MESSAGE_NOT_FOUND | Truncate from not in this conversation |
| 409 | AGENTIC_MESSAGE_ROLE_CONFLICT | Upsert changes a stored message's role |
| 409 | AGENTIC_HISTORY_LIMIT | A cap; extensions.limit names it |
| 409 | AGENTIC_HISTORY_OFF | Create or upsert while the assistant is off |
| 413 | AGENTIC_MESSAGE_TOO_LARGE | One message over 256 KiB |
| 413 | PAYLOAD_TOO_LARGE | A body over 2 MiB |
Summary turns
The client folds old messages into summary through the same prepare and gateway as a chat turn, so the app's model, the quota and the turn guard apply. Summary turns exist on the engine path only (an app is selected). With no app selected, prepare is 404 AGENTIC_NOT_ENGINE. The env path has no summary in v1.
How the client calls it
Pick the messages to fold, for example everything before the last few turns. Note the
seqof the last one.Prepare a new turn with
purpose: 'summary'. Use a freshturn_id.historymust be empty.queryis only hashed, never stored: send the text you fold or a digest of it.httpPOST /ai/agentic/prepare { "turn_id": "sum_Hk2nq81LpX0aZ3sT", "query": "<text to fold>", "purpose": "summary" } 200 { "data": { "kind": "llm", "turn_id": "sum_Hk2nq81LpX0aZ3sT", "model": "<integration_id>:<model_id>", "integration_id": "…", "skills_loaded": [], "citations": [] } }Call the gateway,
POST /ai/agentic/v1/chat/completions, with thatmodel, the user's token and the headerX-ODP-Turn-Id: <turn_id>. The request shape:stream: trueis required. The gateway serves streamed completions only, summary turns included;streamabsent orfalseis 400invalid_payload, and no call is used;- the summary instruction goes in the leading
systemmessage, the only system message allowed; - the old summary, if any, and the folded messages go as
userandassistantmessages, as text; - no
tools,tool_choice,functions,function_callorparallel_tool_calls; max_tokensis optional: a value at or under the summary cap is kept, anything else becomes the cap. The summary cap is the app'smax_output_tokenswhen it is set and lower than 2048, otherwise 2048.
json{ "model": "<integration_id>:<model_id>", "stream": true, "max_tokens": 1024, "messages": [ { "role": "system", "content": "Update the summary with the new messages." }, { "role": "user", "content": "Summary so far: …" }, { "role": "user", "content": "Refund policy?" }, { "role": "assistant", "content": "30 days." } ] }Read the SSE answer as for a chat turn, cut it to 4 000 characters, and save it:
PATCH /ai/agentic/conversations/:id { "summary": "…", "summary_seq": <seq of the last folded message> }.
What the engine does
prepareruns no flow: no knowledge, no skills, no tools, no app system prompt. It returns the model a chat turn would hand off (a chatbot's own binding, or the final llm of a flow).- The purpose is part of the turn: a
turn_idprepared for the other purpose is 409AGENTIC_TURN_CONFLICT. - On a summary turn the gateway:
- refuses the tool fields above, a
toolmessage, non-text content and a body with no text, with 400invalid_payload; - builds one system message: your leading system text, then its fixed summarizer prompt (
SUMMARY_SYSTEM_PROMPT), never the app's; - folds every other message into one user message, inside a
<conversation>block marked as data, with<escaped. Only the leading system message is read as an instruction; - caps the output at min(the app's
max_output_tokensif set,SUMMARY_MAX_TOKENS2048). The app's value is the admin's cost cap, so a summary never goes above it. A smaller caller value is kept.
- refuses the tool fields above, a
- A refused body uses up neither the quota nor a call of the turn.
- Quota: one point for the
prepare, one for the gateway call. - The turn closes when the model finishes.
- Gateway errors keep the OpenAI shape
{ error: { message, type, code } }.
A summary is derived from user text: put it back into a later prompt as data (client rule 5).
Nothing else in the LLM path changes.
What stays out
- No
odp_activity, no revisions and no item events for these rows (the purge writes its one activity row). - Both tables are system tables, so
/items, import, export and the MCP item tools refuse them. - Anyone with database access can still read them: "admin cannot read" holds through the API only.
- The prune cutoff and the purge
beforeare computed by the database, so Node's time zone plays no part. MySQL needsfix/mysql-fresh-migrate(UTC sessions) or later.