Quickstart

npm install @versoai/core

import { signLink } from "@versoai/core";

const { url } = await signLink(
  {
    appId: "app_yourapp",
    userRef: user.id,               // your identifier for this user, returned in every webhook
    scopes: ["conversations:read"],
    purpose: "connect",
  },
  process.env.VERSO_APP_SECRET!,
);

res.redirect(url);                  // https://connect.tryverso.ai/start?token=…

import express from "express";
import { verifyWebhook } from "@versoai/core";
import type { WebhookEvent } from "@versoai/core";

const app = express();

app.post("/webhooks/verso", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  const signature = req.get("x-verso-signature") ?? "";

  if (!verifyWebhook(process.env.VERSO_WEBHOOK_SECRET!, signature, body)) {
    return res.status(401).send("Bad signature");
  }

  const event = JSON.parse(body) as WebhookEvent;

  switch (event.event) {
    case "connection.created":
      // event.payload.userRef is connected; syncing has started
      break;
    case "reauth.needed":
      // send event.payload.userRef a new connect link
      break;
    case "data.imported":
      // event.payload.inserted new conversations for event.payload.userRef
      break;
  }

  res.sendStatus(200);
});

curl -s "https://connect.tryverso.ai/api/connections?userRef=user_123" \
  -H "Authorization: Bearer $VERSO_API_KEY"

{
  "userRef": "user_123",
  "connected": true,
  "needsReauth": false,
  "recentConversationCount": 12,
  "recentWindowDays": 30,
  "connections": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "provider": "chatgpt",
      "status": "active",
      "capturedAt": "2026-09-20T10:00:00Z",
      "lastSyncAt": "2026-09-29T14:41:11Z",
      "conversationCount": 142,
      "recentConversationCount": 12
    }
  ]
}

curl -s "https://connect.tryverso.ai/api/conversations?connectionId=550e8400-e29b-41d4-a716-446655440000&limit=100" \
  -H "Authorization: Bearer $VERSO_API_KEY"

{
  "conversations": [
    {
      "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" },
          { "role": "assistant", "content": "I'll help you build a task management API…", "timestamp": "2026-09-20T10:00:05.000Z", "model": "gpt-4o" }
        ]
      }
    }
  ],
  "total": 142,
  "limit": 100,
  "offset": 0
}