REST API Specs¶

The Angular library talks to the backend through a small REST API. The Spring Boot integration implements it, and any other backend that implements the same contract works with the Angular library too.

The full machine-readable contract is the OpenAPI spec in docs/openapi.yaml in the repository. This page sums it up.

Conventions¶

• All endpoints live under /assistant.
• Every session belongs to one agent, and a session id is only unique within that agent. Sessions are therefore always addressed under their agent: /assistant/agents/{agentId}/sessions/{sessionId}.
• Request and response bodies are JSON. The chat endpoint is the exception: it answers with server-sent events.
• The API does not authenticate requests itself. The host application secures /assistant/**, for example with Spring Security (see Spring Integration).
• The endpoints that read or change chat history (sessions, events, close, grants) answer 404 when the backend keeps no history. The question endpoint answers 404 when the backend doesn't support questions.
• When the backend checks access, any endpoint can answer 401 (the caller is not authenticated) or 403 (the caller is not allowed, for example on a session it doesn't own and that wasn't shared with it).

Endpoints¶

List the agents¶

GET /assistant/agents

Returns the public agents as an array of AgentDetails. The first agent is the default. Private agents, such as the internal title-agent, are left out.

[
  {
    "id": "memory-agent",
    "name": "Memory Agent",
    "description": null,
    "hasMemory": true,
    "reportToolCalls": true,
    "reportThinking": true
  }
]

Chat with an agent¶

POST /assistant/agents/{agentId}/chat

Sends the conversation to the agent and streams the run back as server-sent events. The body is a ChatRequest:

{
  "sessionId": null,
  "messages": [
    { "role": "user", "content": [{ "type": "text", "text": "Hello!" }] }
  ]
}

• A request without a sessionId (or with a blank one) starts a new session. The new id is sent in the first title event.
• The latest user message is the prompt of this turn. A request with no assistant message is treated as the first turn, and the backend generates a title for the conversation.
• The backend drops system and developer messages sent by the client, unless aeon.assistant.allow-client-system-messages is enabled.
• A session runs one request at a time.
• The stream times out after one hour. Closing the stream cancels the run.

The error statuses are only returned before streaming starts. If the run fails after the stream has started, the stream is aborted.

Chat stream¶

The event field of each server-sent event names the kind of event, and data holds its JSON payload:

event:title
data:{"title":"Greetings","sessionId":"0b6c6f0e-2f4e-4b8e-9f3e-5c1d2a7b9e10"}

event:message
data:{"timestamp":"2026-10-05T09:25:00Z","role":"assistant","content":[{"type":"text","text":"Hi! How can I help?"}],"agentId":"assistant","agentName":"Assistant","type":"message"}

List sessions¶

GET /assistant/agents/{agentId}/sessions

Returns the sessions of the agent as an array of ChatSession, most recently used first.

Delete all sessions¶

DELETE /assistant/agents/{agentId}/sessions

Deletes every session of the agent along with its history. A run still in progress is allowed to finish, and anything it reports afterwards is recorded as a new session.

Delete a session¶

DELETE /assistant/agents/{agentId}/sessions/{sessionId}

Deletes a session along with its history. A run still in progress is allowed to finish, and anything it reports afterwards is recorded as a new session.

Rename a session¶

PUT /assistant/agents/{agentId}/sessions/{sessionId}/title

Renames a session. Only its owner can do this. Once renamed, the session keeps this title: the title generated on the first turn no longer replaces it. The body is a SessionTitle:

{ "title": "Weather in Paris" }

Read history¶

GET /assistant/agents/{agentId}/sessions/{sessionId}/events?from={timestamp}

Returns the events of a session in the order they happened, as an array of ChatEvent, so the client can show the conversation again. Events the client would not have seen live are left out: tool calls, the text written between them, and the reasoning of agents that don't report it.

The optional from query parameter (ISO-8601 date-time, for example 2026-10-05T09:00:00Z) only returns the events that happened at that time or later.

Close a session¶

POST /assistant/agents/{agentId}/sessions/{sessionId}/close

Closes a session. It no longer accepts messages: later chat requests on it fail with 409. A run still in progress is allowed to finish.

Answer a question¶

POST /assistant/agents/{agentId}/sessions/{sessionId}/questions/{questionId}

Sends the user's answers to a question the agent is waiting on, as announced by a question event of the chat stream. The body is an array of QuestionAnswer:

[
  { "name": "color", "selected": ["Blue"], "text": "A dark shade if possible" }
]

Session grants¶

The owner of a session can share it with other users. A grantee can send messages, read the history, close the session and answer its questions, but can't rename it, delete it or manage its grants. Only the owner can call these endpoints.

{ "sessionId": "0b6c6f0e-2f4e-4b8e-9f3e-5c1d2a7b9e10", "type": "USER", "grantee": "alice" }

Schemas¶

Fields marked "nullable" may be null or missing.

AgentDetails¶

An agent the client can talk to.

Agents with hasMemory: true only need the new message. For other agents, the client sends the whole conversation with every request.

ChatSession¶

An existing session.

SessionTitle¶

ChatRequest¶

TitleEvent¶

The first event of every chat stream.

ChatEvent¶

An event of a conversation, as returned by the history endpoint. It is one of Message, TextEvent, ThinkingEvent or ToolExecutionEvent, told apart by type. Every event has these fields:

The server writes type but doesn't need it when reading: a payload without type is read the same way.

Message¶

A message of the conversation (type: message).

TextEvent¶

Text the model wrote between tool calls (type: text).

ThinkingEvent¶

Reasoning the model produced before answering (type: thinking).

ToolExecutionEvent¶

A tool call (type: tool). Each call is reported twice: first as STARTED, then as COMPLETED or FAILED, both with the same toolCallId.

Content¶

A part of a message, told apart by type. A part without a type is read as text.

QuestionRequest¶

A set of questions sent to the client while a run is in progress (question event). Answer it with the question endpoint.

UserQuestion¶

A single question asked to the user. Free-form text is always accepted in addition to the options.

QuestionOption¶

SessionGrant¶

QuestionAnswer¶

The user's answer to one question.