> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryverso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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](/guides/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 |

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

## 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:

```json theme={null}
{
  "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                                            |