Chat sessions
A chat session is one conversation, owned by the user who created it. These endpoints list your sessions, read the messages in a session, copy a session's opening message and metrics, and rename or delete a session.
Every endpoint is scoped to the caller: you can only read or change sessions you own. A request for a session belonging to another user is refused with 403.
The chat session object
One conversation and its most recent activity.
Attributes
-
idintegerThe session's unique identifier.
-
agent_typestringThe kind of agent the session was started with.
-
titlestringThe session's title. Defaults to
New Chatuntil renamed. -
user_idintegerThe owning user's identifier.
-
created_atstringWhen the session was created.
-
last_messagenullable stringThe content of the most recent message, or null when the session has none.
-
latest_metricsnullable objectThe most recent metrics recorded for the session, or null.
Show child attributes Hide child attributes
-
idintegerThe metrics record's identifier.
-
typestringThe kind of metrics recorded.
-
dataobjectThe metrics payload.
-
{
"id": 128,
"agent_type": "master",
"title": "Q3 board narrative",
"user_id": 42,
"created_at": "Tue, 01 Sep 2026 09:30:00 GMT",
"last_message": "Here is the summary you asked for.",
"latest_metrics": null
}List chat sessions
GET /api/chat-sessions
Returns the caller's chat sessions, newest first.
Returns the sessions owned by the caller, most recently created first. Supply page or limit to page through the list; when neither is present, every session is returned in one response without the pagination fields.
- Authentication
- Bearer token How it works
Query parameters
-
pageintegerThe 1-based page to return. Values below 1 are treated as 1.
-
limitintegerSessions per page, from 1 to 100. Values outside that range fall back to the default.
Returns
Returns a page of chat session objects.
curl "$VDF_BASE_URL/api/chat-sessions?page=1&limit=20" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/api/chat-sessions?page=1&limit=20`, {
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.get(
f"{os.environ['VDF_BASE_URL']}/api/chat-sessions",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
params={
"page": 1,
"limit": 20,
},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"sessions": [
{
"id": 128,
"agent_type": "master",
"title": "Q3 board narrative",
"user_id": 42,
"created_at": "Tue, 01 Sep 2026 09:30:00 GMT",
"last_message": "Here is the summary you asked for.",
"latest_metrics": null
}
],
"total": 1,
"page": 1,
"limit": 20,
"hasMore": false
}List messages in a session
GET /api/chat/messages/{session_id}
Returns the messages in a session the caller owns.
Returns the messages in a session, oldest first. Restrict the result with mission_id, cap it with limit, or set latest=true alongside a limit to take the newest messages (still returned in chronological order). The caller must own the session.
- Authentication
- Bearer token How it works
Path parameters
-
session_idinteger RequiredThe session to read.
Query parameters
-
mission_idstringReturn only messages belonging to this mission.
-
limitintegerMaximum number of messages to return, up to 1000.
-
latestbooleanWhen true and a
limitis set, take the newest messages rather than the oldest.
Returns
Returns the session's messages in messages.
Errors
- 403 The session does not belong to the caller.
curl "$VDF_BASE_URL/api/chat/messages/128?limit=50" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/api/chat/messages/128?limit=50`, {
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.get(
f"{os.environ['VDF_BASE_URL']}/api/chat/messages/128",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
params={
"limit": 50,
},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"messages": [
{
"role": "user",
"content": "Summarise the attached report.",
"timestamp": "2026-09-01T09:30:00+00:00",
"html_generation_id": null,
"mission_id": null,
"message_type": null,
"step_index": null,
"step_id": null
},
{
"role": "assistant",
"content": "Here is the summary you asked for.",
"timestamp": "2026-09-01T09:30:42+00:00",
"html_generation_id": null,
"mission_id": null,
"message_type": null,
"step_index": null,
"step_id": null
}
]
}Retrieve a session's opening message
GET /api/chat/{session_id}/copy
Returns a session's opening message and metrics for reuse.
Returns the first user message of a session together with its recorded metrics, so the conversation can be started again from the same prompt. The caller must own the session.
- Authentication
- Bearer token How it works
Path parameters
-
session_idinteger RequiredThe session to copy from.
Returns
Returns the opening message and metrics in data.
Errors
- 403 The session does not belong to the caller.
- 404 The session has no message to copy.
curl "$VDF_BASE_URL/api/chat/128/copy" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/api/chat/128/copy`, {
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.get(
f"{os.environ['VDF_BASE_URL']}/api/chat/128/copy",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"data": {
"message": "Summarise the attached report.",
"metrics": [
{
"metrics_type": "clarity",
"metrics_data": {
"score": 0.82
}
}
]
}
}Rename a session
PUT /api/chat/{session_id}/rename
Changes the title of a session the caller owns.
Sets a new title on a session. The caller must own the session.
- Authentication
- Bearer token How it works
Path parameters
-
session_idinteger RequiredThe session to rename.
Body parameters application/json
-
titlestring RequiredThe new title.
Returns
Returns success: true, a confirmation message, and the new title.
Errors
- 400 The request body is missing or
titlewas not supplied. - 403 The session does not belong to the caller.
curl -X PUT "$VDF_BASE_URL/api/chat/128/rename" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Q3 board narrative"
}'const response = await fetch(`${process.env.VDF_BASE_URL}/api/chat/128/rename`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'Q3 board narrative',
}),
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.put(
f"{os.environ['VDF_BASE_URL']}/api/chat/128/rename",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
json={
"title": "Q3 board narrative",
},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"message": "Session renamed successfully",
"title": "Q3 board narrative"
}Delete a session
DEL /api/chat/{session_id}
Deletes a session the caller owns and all of its data.
Permanently deletes a session together with its messages, metrics, and any diagram. The caller must own the session. This cannot be undone.
- Authentication
- Bearer token How it works
Path parameters
-
session_idinteger RequiredThe session to delete.
Returns
Returns success: true and a confirmation message once the session and its messages are deleted.
Errors
- 403 The session does not belong to the caller.
curl -X DELETE "$VDF_BASE_URL/api/chat/128" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/api/chat/128`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.delete(
f"{os.environ['VDF_BASE_URL']}/api/chat/128",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"message": "Chat session deleted successfully"
}