Skip to content

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), create and update (PUT), delete (DELETE and purge).
  • The ai module 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.

  1. 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.
  2. Never store tool output, errorText, image bytes or data: URLs, keys or tokens, or decrypted turn content (app system prompt, knowledge). See What a client must never store for what to store instead.
  3. Mark an incomplete tool part as interrupted before you save it, so a restore never looks like a call still running.
  4. 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_patch is inert.
  5. Put the summary in as data. When a saved summary goes 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.
  6. 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 409 AGENTIC_HISTORY_OFF, keep the chat going unsaved. A save error must never fail or block a chat turn.
  7. Regenerate with a truncate. Before you save a regenerated answer, delete from the old one (DELETE …/messages?from=), or the store keeps both.
  8. 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 add meta.
  • 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 + pathRequestResponse
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/:id200 { data: ConversationDetail }
PATCH /ai/agentic/conversations/:id{ title?, summary?, summary_seq? }200 { data: ConversationDetail }
DELETE /ai/agentic/conversations/:id204
GET /ai/agentic/conversations/:id/messages?limit=1–500 (200), ?after or ?before200 { data: Message[], meta: { message_count } }
PUT /ai/agentic/conversations/:id/messages{ messages: [{ id, role, parts }] }, 1–8200 { data: Message[] }
DELETE /ai/agentic/conversations/:id/messages?from=<id>200 { data: { deleted } }
POST /ai/agentic/history/purge{ user_id?, before? }, admin only200 { 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-…

204

Read 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 limit messages. Use it to open a conversation. With limit=500, the cap, one call loads all of it.
  • ?before=<seq>: the limit messages just before seq. To scroll back, pass the seq of the first message you hold. More remain while that first seq is above 1.
  • ?after=<seq>: the first limit messages after seq. To build the model context, pass summary_seq and send the summary plus these messages.
  • after and before together are 400. limit, offset, after and before must 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 id already in this conversation keeps its seq and date_created, and its parts is replaced. The same id with another role is 409 AGENTIC_MESSAGE_ROLE_CONFLICT, and nothing of the request is written;
  • a new id is appended with the next seq;
  • the same id in another conversation is a different message;
  • message_count, the stored size and date_updated change 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.

  1. Delete from the old assistant message: DELETE …/messages?from=<old id>.
  2. 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_count becomes seq(from) − 1;
  • if summary_seq is at or after seq(from), summary and summary_seq are cleared, because the summary covered a deleted message;
  • an id not in this conversation is 404 AGENTIC_MESSAGE_NOT_FOUND; no from is 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 delete scope.
  • Body { "user_id": "<uuid>" }, { "before": "<ISO date>" } (compared with date_updated), or both. At least one is required; { "before": <now> } purges everything.
  • The answer is counts only, never rows.
  • One odp_activity row (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:

  • id matches ^[A-Za-z0-9_-]{1,128}$ and is case-sensitive (aB1 and Ab1 are two messages);
  • role is user or assistant. A system message is never stored;
  • parts is an array of at most 200 objects, each with a string type. Nothing deeper is checked, so a new AI SDK part type needs no API change;
  • a part whose url or data is a data: URL is 400.

What a client must never store ​

Client rule. The API cannot check these; the client must keep them out:

Never storeStore 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 partThe state only
Image bytes or a data: URLThe text [image sent: <name>]
Keys, tokens, passwordsNothing
Decrypted turn content (the app system prompt, knowledge from prepare)Nothing: it never reaches the client
Reasoning partsNothing
UIMessage.metadataNothing

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_present program. On restore it renders with the viewer's current rights and the URL safety gate;
  • the dashboard.propose_patch patch, shown inert.

An unfinished tool part is stored as interrupted, and restoring runs nothing (client rules 3 and 4).

Caps ​

CapValueOn reach
One message (serialized parts)256 KiB413 AGENTIC_MESSAGE_TOO_LARGE
Request body of PUT …/messages2 MiB413 PAYLOAD_TOO_LARGE
Messages per conversation500409 AGENTIC_HISTORY_LIMIT, extensions.limit: "messages"
Bytes per conversation8 MiB409 AGENTIC_HISTORY_LIMIT, limit: "conversation_bytes"
Conversations per user200409 AGENTIC_HISTORY_LIMIT, limit: "conversations"
Bytes per user64 MiB409 AGENTIC_HISTORY_LIMIT, limit: "user_bytes"
title255 characters400
summary32 KiB400

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, or null for the default. GET /ai/agentic/config returns it.
  • On the first save, enabled is 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" } }] }
StatusCodeWhen
400INVALID_PAYLOADSchema, 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
401INVALID_CREDENTIALSNo user
403FORBIDDENNo app access, an impersonation session, a sub-token without the scope, purge by a non-admin
404AGENTIC_CONVERSATION_NOT_FOUNDUnknown id, or another user's
404AGENTIC_MESSAGE_NOT_FOUNDTruncate from not in this conversation
409AGENTIC_MESSAGE_ROLE_CONFLICTUpsert changes a stored message's role
409AGENTIC_HISTORY_LIMITA cap; extensions.limit names it
409AGENTIC_HISTORY_OFFCreate or upsert while the assistant is off
413AGENTIC_MESSAGE_TOO_LARGEOne message over 256 KiB
413PAYLOAD_TOO_LARGEA 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 ​

  1. Pick the messages to fold, for example everything before the last few turns. Note the seq of the last one.

  2. Prepare a new turn with purpose: 'summary'. Use a fresh turn_id. history must be empty. query is only hashed, never stored: send the text you fold or a digest of it.

    http
    POST /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": [] } }
  3. Call the gateway, POST /ai/agentic/v1/chat/completions, with that model, the user's token and the header X-ODP-Turn-Id: <turn_id>. The request shape:

    • stream: true is required. The gateway serves streamed completions only, summary turns included; stream absent or false is 400 invalid_payload, and no call is used;
    • the summary instruction goes in the leading system message, the only system message allowed;
    • the old summary, if any, and the folded messages go as user and assistant messages, as text;
    • no tools, tool_choice, functions, function_call or parallel_tool_calls;
    • max_tokens is optional: a value at or under the summary cap is kept, anything else becomes the cap. The summary cap is the app's max_output_tokens when 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." }
    ] }
  4. 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 ​

  • prepare runs 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_id prepared for the other purpose is 409 AGENTIC_TURN_CONFLICT.
  • On a summary turn the gateway:
    • refuses the tool fields above, a tool message, non-text content and a body with no text, with 400 invalid_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_tokens if set, SUMMARY_MAX_TOKENS 2048). The app's value is the admin's cost cap, so a summary never goes above it. A smaller caller value is kept.
  • 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 before are computed by the database, so Node's time zone plays no part. MySQL needs fix/mysql-fresh-migrate (UTC sessions) or later.

ODP Internal API Documentation