Data management

Status and recent activity

GET /api/connections?userRef= answers the two questions you have about a user: are they connected, and how active have they been.

{
  "userRef": "user_123",
  "connected": true,
  "needsReauth": false,
  "recentConversationCount": 12,
  "recentWindowDays": 30,
  "connections": [ { "id": "…", "status": "active", "conversationCount": 142, "recentConversationCount": 12, "…": "…" } ]
}

connected is true when at least one connection is active.
needsReauth is true when at least one connection is needs_reauth. This is the only status that should trigger a “please reconnect” message. A revoked connection was either replaced after a reconnect or deleted by the user on purpose.
recentConversationCount counts conversations whose first message is dated within the last 30 days, evaluated at request time. It measures what the user did, not what Verso imported: an old history imported yesterday counts for nothing, and continuing an old conversation does not move it into the window.

Always query by userRef. Connection ids change when a user reconnects, and one user may hold several connections. An expired session is detected at the next sync, so connected can stay true for a few hours after the provider invalidated the session. lastSyncAt tells you when it was last verified.

Reading conversations

GET /api/conversations?connectionId= returns pages of conversations, newest update_time first.

async function fetchAll(connectionId: string) {
  const all = [];
  for (let offset = 0; ; offset += 100) {
    const res = await fetch(
      `https://connect.tryverso.ai/api/conversations?connectionId=${connectionId}&limit=100&offset=${offset}`,
      { headers: { Authorization: `Bearer ${process.env.VERSO_API_KEY}` } },
    );
    const page = await res.json();
    all.push(...page.conversations);
    if (all.length >= page.total) return all;
  }
}

Because the list is ordered by update_time, a conversation the user continues moves back to the top. To detect changes cheaply, compare update_time with what you stored.

Shape of a conversation

{
  "id": "6a1f…",
  "external_id": "68d9c2a1-3f0e-8005-b2c1-7e2f0d1a9b3c",
  "title": "Help me build a REST API",
  "update_time": "2026-09-20T10:05:00Z",
  "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:00.000Z",
        "id": "aaa-…",
        "contentType": "text"
      },
      {
        "role": "assistant",
        "content": "I'll help you build a task management API…",
        "timestamp": "2026-09-20T10:00:05.000Z",
        "id": "bbb-…",
        "contentType": "text",
        "model": "gpt-4o",
        "status": "finished_successfully",
        "endTurn": true
      }
    ]
  }
}

messages is the conversation’s current branch in chronological order. System messages and empty nodes are dropped; messages the user regenerated or branched away from are not included.

Field	Always present	Description
`role`	Yes	`user`, `assistant` or `tool`
`content`	Yes	Text. Empty when the message only carries attachments.
`timestamp`	Yes	ISO 8601, or `null` when the provider gave none
`id`	Usually	The provider’s message id
`contentType`	Usually	`text`, `multimodal_text`, `code`…
`model`	Assistant messages	Model that produced the message, e.g. `gpt-4o`
`status`, `endTurn`	Usually	Provider status flags
`attachments`	When present	Files and images: `type`, `asset_pointer`, `name`, `size_bytes`, `width`, `height`
`contentReferences`	When present	Citations embedded in an assistant answer

Attachments are metadata only for now. The files are stored by Verso but cannot be retrieved through the API yet.

Sync cadence

Every connection is synced by a background worker that lists the account’s conversations, fetches the ones that changed, and stores them. The pace adapts to the account and to the provider’s limits.

Situation	Next sync
Right after the connection	Within a minute
History still being backfilled	Every 15 minutes, until the whole history is imported
Last sync found something new	4 hours
Last sync found nothing	Twice the previous interval, up to 48 hours
The provider rate-limited the account	1 hour

The initial backfill fetches the most recent conversations first, then works backwards; a large history takes hours because the provider limits how fast one account can be read. Each sync that inserts or updates at least one conversation sends data.imported.

Re-authentication

When the provider rejects the stored session, the connection becomes needs_reauth and reauth.needed is sent. Sign a new connect link:

const { url } = await signLink(
  { appId: "app_yourapp", userRef, scopes: ["conversations:read"], purpose: "connect" },
  process.env.VERSO_APP_SECRET!,
);
// send url to the user

After the user logs in, the new connection replaces the old one and sync resumes where it stopped. The conversations already imported stay readable in the meantime.

Getting started

Guides

Resources

Status and recent activity

Reading conversations

Shape of a conversation

Sync cadence

Re-authentication

​Status and recent activity

​Reading conversations

​Shape of a conversation

​Sync cadence

​Re-authentication

Status and recent activity

Reading conversations

Shape of a conversation

Sync cadence

Re-authentication