Conversations
Note
Legacy. These endpoints are kept for compatibility. OnVeris Chat uses a newer conversations API that is not documented for general use. For a conversation history kept by the Gateway in your own integration, use Responses.
The conversations endpoints let you list, retrieve, create, update and delete the chat conversations stored on the Gateway. These are the same conversations visible in OnVeris Chat.
Note
These endpoints need an access token from signing in. API Keys are not accepted — conversations are tied to a specific user account.
Base Path
/onveris/v1/conversations
List Conversations
GET /onveris/v1/conversations
This returns a paginated list of conversations for the authenticated user, ordered by most recently active first.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
startIndex |
integer | 0 | Zero-based offset into the result set. |
returnCount |
integer | 50 | Number of conversations to return. Maximum 200. |
Response
{
"total": 42,
"startIndex": 0,
"returnCount": 10,
"items": [
{
"conversationId": "a1b2c3d4-...",
"conversationName": "Explain quantum entanglement",
"lastActiveAt": "2026-04-07T14:32:00Z"
}
]
}
Status Codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 401 | Not authenticated (access token required) |
| 503 | Gateway unavailable |
Get A Conversation
GET /onveris/v1/conversations/{id}
This returns the full conversation record for the given ID.
Response
{
"id": "a1b2c3d4-...",
"userId": "f9e8d7c6-...",
"title": "Explain quantum entanglement",
"modelId": "llama-3.1-8b",
"turnCount": 6,
"status": "Idle",
"lastActiveAt": "2026-04-07T14:32:00Z",
"createdAt": "2026-04-07T12:00:00Z",
"updatedAt": "2026-04-07T14:32:00Z"
}
Conversation Fields
| Field | Description |
|---|---|
id |
Unique conversation identifier. |
userId |
The user who owns this conversation. |
title |
Display title. Defaults to "New Chat". |
modelId |
The model used in this conversation. |
turnCount |
Number of completed user+assistant exchanges. |
status |
"Idle", "Running", or "Error". |
lastActiveAt |
When the most recent message was added. |
createdAt |
When the conversation was created. |
updatedAt |
When the conversation record was last written. |
Status Codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 401 | Not authenticated |
| 403 | Conversation belongs to a different user |
| 404 | Conversation not found |
| 503 | Gateway unavailable |
Create Or Update A Conversation
PUT /onveris/v1/conversations
This creates a new conversation, or updates an existing one. To update, include the existing id. To create, omit id or send an empty GUID.
Request Body
{
"id": "a1b2c3d4-...",
"title": "My updated title",
"modelId": "llama-3.1-8b"
}
Only the fields you include will influence the result. userId is always resolved from the authenticated token, whatever is sent.
Status Codes
| Code | Meaning |
|---|---|
| 201 | Created (new conversation) |
| 200 | Updated (existing conversation) |
| 400 | Missing or invalid payload |
| 401 | Not authenticated |
| 403 | Attempting to update a conversation owned by another user |
| 503 | Gateway unavailable |
Delete A Conversation
DELETE /onveris/v1/conversations/{id}
This permanently deletes the conversation and all its messages.
Status Codes
| Code | Meaning |
|---|---|
| 204 | Deleted successfully |
| 401 | Not authenticated |
| 403 | Conversation belongs to a different user |
| 404 | Conversation not found |
| 503 | Gateway unavailable |
Get Messages
GET /onveris/v1/conversations/{id}/messages
This returns the ordered list of messages belonging to a conversation.
Response
An array of message objects:
[
{
"id": "11111111-...",
"conversationId": "a1b2c3d4-...",
"sequenceNumber": 0,
"role": "user",
"contentType": "text",
"content": "Explain quantum entanglement",
"isComplete": true,
"createdAt": "2026-04-07T12:00:00Z",
"completedAt": "2026-04-07T12:00:00Z"
},
{
"id": "22222222-...",
"conversationId": "a1b2c3d4-...",
"sequenceNumber": 1,
"role": "assistant",
"contentType": "text",
"content": "Quantum entanglement is a phenomenon...",
"modelId": "llama-3.1-8b",
"isComplete": true,
"inputTokens": 42,
"outputTokens": 210,
"finishReason": "stop",
"createdAt": "2026-04-07T12:00:01Z",
"completedAt": "2026-04-07T12:00:04Z"
}
]
Message Fields
| Field | Description |
|---|---|
id |
Unique message identifier. |
conversationId |
The owning conversation. |
sequenceNumber |
Zero-based insertion order within the conversation. |
role |
"user" or "assistant". |
contentType |
"text" for plain messages; "agent_run" for agentic assistant turns. |
content |
The message text. null while a response is still being generated. |
isComplete |
false while streaming or an agent loop is in progress. |
modelId |
Model that generated this message (assistant messages only). |
inputTokens |
Prompt token count (assistant messages only). |
outputTokens |
Completion token count (assistant messages only). |
finishReason |
"stop", "length", "tool_calls" and so on (assistant messages only). |
createdAt |
When the message row was created. |
completedAt |
When the message was fully written. null if still in progress. |
Status Codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 401 | Not authenticated |
| 403 | Conversation belongs to a different user |
| 404 | Conversation not found |
| 503 | Gateway unavailable |