Chat History

The Chat History API manages the persistent conversation sessions created by the AI Agent. Each session groups the messages exchanged in one conversation. Use these endpoints to list past sessions, load a full transcript, rename a session, or delete one. All paths are relative to the base URL and require authentication. All responses use the standard envelope.

List sessions

Return recent chat sessions, newest first. Optionally filter to a single ontology.

GET /chat-history/sessions

Parameter	In	Required	Default	Description
`ontology_id`	query	no	—	Filter sessions to a single ontology. Omit to return all of the user’s sessions across every ontology.
`project_id`	query	no	—	Deprecated alias for `ontology_id`.
`limit`	query	no	`50`	Maximum sessions to return (1–200).

curl "$BASE_URL/chat-history/sessions?ontology_id=$ONTOLOGY_ID&limit=20" \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Found 2 session(s)",
  "data": [
    {
      "id": "sess_a1b2...",
      "ontology_id": "28b8678395e",
      "title": "Modeling supplier risk",
      "created_at": "2026-06-24T08:30:00+00:00",
      "updated_at": "2026-06-24T09:10:00+00:00"
    }
  ]
}

The session_id here is the same identifier the AI Agent chat endpoint accepts. Load a past session, then keep sending chat messages with that session_id to continue the conversation.

Get a session

Load a single session along with all of its messages.

GET /chat-history/sessions/{session_id}

Parameter	In	Required	Default	Description
`session_id`	path	yes	—	The session ID.

curl "$BASE_URL/chat-history/sessions/sess_a1b2..." \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Session loaded",
  "data": {
    "id": "sess_a1b2...",
    "ontology_id": "28b8678395e",
    "title": "Modeling supplier risk",
    "created_at": "2026-06-24T08:30:00+00:00",
    "messages": [
      { "role": "user", "content": "Find all transitive suppliers", "created_at": "2026-06-24T08:30:01+00:00" },
      { "role": "assistant", "content": "Let me create that concept.", "tool_calls": [{ "id": "call_1", "type": "function", "function": { "name": "create_concept", "arguments": "{...}" } }], "created_at": "2026-06-24T08:30:05+00:00" },
      { "role": "tool", "content": "{\"id\": \"concept-uuid\"}", "tool_call_id": "call_1", "created_at": "2026-06-24T08:30:06+00:00" },
      { "role": "assistant", "content": "I created the transitive_suppliers concept...", "created_at": "2026-06-24T08:30:10+00:00" }
    ]
  }
}

Messages are stored in OpenAI wire format, ordered oldest-first:

role is user, assistant, tool, or system.
content may be null on an assistant turn that only makes tool calls.
tool_calls (assistant) is the raw OpenAI array; each has id, type, and function: { name, arguments } where arguments is a JSON string.
tool_call_id (tool role) links a tool result back to its call.
There is no persisted thinking field — the reasoning stream is only emitted live over the agent chat response, not stored.

To render a past conversation, show the user and assistant (content) turns; tool rows are internal. Returns 404 if no session with that ID exists.

Rename a session

Set a new title for a session. The title must be non-empty.

PATCH /chat-history/sessions/{session_id}

Parameter	In	Required	Default	Description
`session_id`	path	yes	—	The session ID.
`title`	body	yes	—	The new session title (non-empty).

curl -X PATCH "$BASE_URL/chat-history/sessions/sess_a1b2..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Supplier risk model v2" }'

{
  "status": "success",
  "message": "Session renamed",
  "data": null
}

Returns 404 if the session does not exist, or 400 if title is missing or empty.

Delete a session

Permanently delete a session and all of its messages.

DELETE /chat-history/sessions/{session_id}

Parameter	In	Required	Default	Description
`session_id`	path	yes	—	The session ID.

curl -X DELETE "$BASE_URL/chat-history/sessions/sess_a1b2..." \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Session deleted",
  "data": null
}

Returns 404 if the session does not exist.

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

List sessions

Get a session

Rename a session

Delete a session

​List sessions

​Get a session

​Rename a session

​Delete a session

List sessions

Get a session

Rename a session

Delete a session