API Overview

Base URL, authentication, and general conventions.

Base URL

All API requests use the following base URL:

https://connect.tryverso.ai

All traffic is routed through a Cloudflare Worker that handles CORS and proxies to the appropriate Supabase Edge Functions.

Authentication

Server-to-server endpoints authenticate via Bearer token using your app secret:

curl https://connect.tryverso.ai/api/conversations \
  -H "Authorization: Bearer YOUR_APP_SECRET"

User-facing pages (/start, /manage) use signed JWT links generated with signLink(). See Authentication for details.

Endpoints

Method	Path	Description	Auth
POST	/api/ingest-export	Ingest an LLM conversation export file	Bearer
GET	/api/conversations?userRef=	List connections for a user	Bearer
GET	/api/conversations?connectionId=	List conversations for a connection	Bearer
POST	/api/purge	Delete user or connection data	Bearer
GET	/start?token=	Hosted connect page	JWT link
GET	/manage?token=	User data management page	JWT link

The connections and conversations listing share the same path (/api/conversations) but are differentiated by the query parameter: userRef returns connections, connectionId returns conversations.

Response format

All API responses return JSON with Content-Type: application/json.

Success responses include endpoint-specific data. Write endpoints include an ok: true field.

Error responses return a single error string:

{
  "error": "Missing connectionId parameter"
}

Rate limiting

API endpoints are rate-limited to 60 requests per minute per app. The rate limiter is database-backed (atomic counter per app per minute bucket).

Rate limit information is included in response headers:

Header	Description
RateLimit-Limit	Maximum requests per window (60)
RateLimit-Remaining	Requests remaining in current window
RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait (only on 429 responses)

HTTP status codes

Code	Meaning
200	Success
400	Bad request (missing or invalid parameters)
401	Authentication failure (missing or invalid token/key)
403	Authorization failure (expired nonce, used JTI, forbidden scope)
404	Resource not found (app, connection, user)
405	Method not allowed
409	Conflict (e.g. connection is revoked)
429	Rate limit exceeded
500	Internal server error