Data model

App (yours)
 └── User          one per (appId, userRef)
      └── Connection   one per connected provider account
           └── Conversation   one per provider conversation
                └── Message

App

Your application, identified by appId. It holds your app secret, your API keys, your webhook URL and secret, and the branding of the hosted pages. Everything below is scoped to one app: the same person connecting through two apps produces two unrelated users, and neither app can see the other’s data.

User

Created the first time a userRef opens a connect link for your app. userRef is your identifier, any string you choose; Verso never interprets it. It is the key of GET /api/connections and appears in every webhook payload.

Connection

A connected provider account of a user.

Field	Description
`id`	UUID. Changes when the user reconnects.
`provider`	`chatgpt`
`status`	`active`, `needs_reauth` or `revoked`
`capturedAt`	When the user completed the connect flow
`lastSyncAt`	Last successful sync, i.e. the last time the session was verified; `null` before the first one
`conversationCount`	Conversations currently imported
`recentConversationCount`	Conversations whose first message is within the last 30 days

Lifecycle:

connect  ──▶  active  ──(session rejected)──▶  needs_reauth  ──(user reconnects)──▶  revoked, replaced by a new active connection
                 │
                 └──(user or partner deletes)──▶  revoked, credentials destroyed

A user may have several connections at once: two different ChatGPT accounts, or an old revoked one next to its replacement. GET /api/connections lists them all.

Conversation

A conversation of the provider account, imported and normalized.

Field	Description
`id`	Verso’s UUID
`external_id`	The provider’s conversation id
`title`	The provider’s title, may be `null`
`update_time`	Last change on the provider side; drives the ordering of `GET /api/conversations`
`payload.messages`	The current branch, chronological, without system messages

A conversation is updated in place when the provider reports a newer update_time; it keeps the same id.

Message

Field	Description
`role`	`user`, `assistant` or `tool`
`content`	Text, possibly empty for attachment-only messages
`timestamp`	When it was written, ISO 8601 or `null`
`id`, `contentType`, `status`, `endTurn`, `model`	Provider metadata when available
`attachments`, `contentReferences`	Files and citations, metadata only

The first message’s timestamp is what recentConversationCount is computed from.

What is not exposed

Session credentials are never returned by any endpoint, not even encrypted. The provider’s raw conversation objects are kept by Verso to re-normalize data when the message format improves, but are not part of the API.

Getting started

Guides

Resources

App

User

Connection

Conversation

Message

What is not exposed

​App

​User

​Connection

​Conversation

​Message

​What is not exposed

App

User

Connection

Conversation

Message

What is not exposed