Skip to content

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