List Conversations

Retrieve imported conversations for a connection.

GET /api/conversations?connectionId=

Lists imported conversations for a given connection, with pagination. Results are ordered by update_time descending (newest first).

Request

Headers

Header	Value
Authorization	Bearer YOUR_APP_SECRET

Query parameters

Param	Type	Required	Default	Description
connectionId	string	Yes	—	The connection UUID
limit	number	No	50	Max results per page (capped at 100)
offset	number	No	0	Number of results to skip

Example

curl -s https://connect.tryverso.ai/api/conversations \
  -H "Authorization: Bearer $VERSO_SECRET" \
  -G -d "connectionId=CONNECTION_ID" \
  -d "limit=50" \
  -d "offset=0"

Response

{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "chatgpt-abc123",
      "title": "Help me build a REST API",
      "payload": {
        "title": "Help me build a REST API",
        "messages": [
          {
            "role": "user",
            "content": "I need a REST API for managing tasks...",
            "timestamp": "2026-09-20T10:00:00Z"
          },
          {
            "role": "assistant",
            "content": "I'll help you build a task management API...",
            "timestamp": "2026-09-20T10:00:05Z"
          }
        ]
      },
      "update_time": "2026-09-20T10:05:00Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Field	Type	Description
conversations	array	List of conversation objects
conversations[].id	string	Internal Verso UUID
conversations[].external_id	string	Provider’s conversation ID
conversations[].title	string?	Conversation title
conversations[].payload	object?	Full conversation data with title and messages array
conversations[].payload.messages	array	Normalized messages: { role, content, timestamp }
conversations[].update_time	string?	Last update time from the provider (ISO 8601)
total	number	Total conversation count for this connection
limit	number	Requested page size
offset	number	Current offset

Message format

Each message in payload.messages has this structure:

Field	Type	Values
role	string	user, assistant, system, or tool
content	string	Message text
timestamp	string?	ISO 8601 timestamp (null if unavailable)

Pagination

Use limit and offset to paginate through results. When offset + conversations.length >= total, you’ve reached the end.

async function fetchAll(connectionId: string, secret: string) {
  const all = [];
  let offset = 0;
  const limit = 100; // max allowed

  while (true) {
    const res = await fetch(
      `https://connect.tryverso.ai/api/conversations?connectionId=${connectionId}&limit=${limit}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${secret}` } },
    );
    const data = await res.json();
    all.push(...data.conversations);
    if (all.length >= data.total) break;
    offset += limit;
  }

  return all;
}

Errors

Status	Error	Cause
400	Missing connectionId parameter	connectionId query param not provided
401	Missing Authorization header	Missing Bearer prefix
401	Invalid API key	Wrong or missing app secret
404	Connection not found	Connection doesn’t exist or belongs to a different app
429	Rate limit exceeded	Exceeded 60 requests/min