Conversations

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 the OptimaGPT chat UI.

Note: These endpoints require a JWT bearer token. API key authentication is not supported — conversations are tied to a specific user account.

Base path

/optima/v1/conversations

List conversations

GET /optima/v1/conversations

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 (JWT required)
503	Gateway unavailable

Get a conversation

GET /optima/v1/conversations/{id}

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 /optima/v1/conversations

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 regardless of what 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 /optima/v1/conversations/{id}

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 /optima/v1/conversations/{id}/messages

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"`, etc. (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