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

# API reference

> Every endpoint, every parameter. Forty-eight surfaces, hand-written.

The Trellis Public API. Forty-eight endpoints across ten groups. Hand-written, with request and response examples in cURL, Python, and JavaScript on every page.

## Base URL

```
https://api.trellis.sh
```

## Authentication

All endpoints (except `/v1/authenticate`) require a valid JWT token in the Authorization header:

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

See the [Authentication guide](/authentication) for details on obtaining a token.

## Request format

* All request bodies must be JSON with `Content-Type: application/json`
* For streaming endpoints, also include `Accept: text/event-stream`

## Response format

All responses return JSON. Successful responses include the requested data directly:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "chats": [...],
  "projects": [...]
}
```

## Error responses

Errors return a JSON object with a `detail` field:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Chat not found"
}
```

### HTTP status codes

| Code | Description                                                  |
| ---- | ------------------------------------------------------------ |
| 200  | Success                                                      |
| 201  | Created                                                      |
| 204  | No Content - success with no response body                   |
| 400  | Bad request - invalid parameters                             |
| 401  | Unauthorized - missing or invalid token                      |
| 403  | Forbidden - admin privileges required                        |
| 404  | Not found - resource doesn't exist                           |
| 409  | Conflict - resource cap reached (e.g. open-chat cap)         |
| 429  | Too many requests - rate limit exceeded; check `Retry-After` |
| 500  | Internal server error                                        |

## Rate limits

Several chat surfaces enforce per-JWT throttles. Each returns `429` with a `Retry-After` header (or, on the WebSocket, an `error` event with `code: "RATE_LIMIT"` and `retry_after_seconds`). See each endpoint page for specifics, or the [Chat Overview → Rate limits](/api-reference/chats/overview#rate-limits) summary.

## Pagination

List endpoints that support pagination return results in pages. Pass a `page` query parameter (1-based) to navigate. Responses include `total`, `page`, `page_size`, and `has_more` fields.

## Endpoint summary

| Method | Endpoint                           | Description                                  |
| ------ | ---------------------------------- | -------------------------------------------- |
| POST   | `/v1/authenticate`                 | Exchange API key for JWT token               |
| GET    | `/v1/models`                       | List available AI models                     |
| GET    | `/v1/integrations`                 | List database integrations                   |
| GET    | `/v1/projects`                     | List projects                                |
| GET    | `/v1/projects/{id}`                | Get a specific project                       |
| GET    | `/v1/queries`                      | List saved queries                           |
| GET    | `/v1/queries/{id}`                 | Get a saved query                            |
| POST   | `/v1/queries`                      | Create a saved query                         |
| PATCH  | `/v1/queries/{id}`                 | Update a saved query                         |
| DELETE | `/v1/queries/{id}`                 | Delete a saved query                         |
| GET    | `/v1/chats`                        | List chats (paginated)                       |
| GET    | `/v1/chats/{id}`                   | Get chat with messages                       |
| POST   | `/v1/chats/create`                 | Create an empty chat and obtain a `chat_id`  |
| POST   | `/v1/chats`                        | Send message (SSE stream)                    |
| POST   | `/v1/chats/uploads`                | Upload files to a chat                       |
| GET    | `/v1/chats/{id}/uploads`           | List uploads for a chat                      |
| DELETE | `/v1/chats/uploads/{id}`           | Delete an upload                             |
| PUT    | `/v1/chats/{id}`                   | Update chat title                            |
| DELETE | `/v1/chats`                        | Delete multiple chats                        |
| DELETE | `/v1/chats/{id}`                   | Delete a chat                                |
| DELETE | `/v1/chats/{id}/messages/{id}`     | Delete a message and all subsequent messages |
| PATCH  | `/v1/chats/{id}/messages/{id}`     | Edit a message and re-stream the response    |
| PATCH  | `/v1/chats/messages/{id}/feedback` | Add message feedback                         |
| POST   | `/v1/chats/followups`              | Get follow-up suggestions                    |
| POST   | `/v1/voice/sessions`               | Create a voice chat session                  |
| GET    | `/v1/tts/messages/{id}/audio`      | Stream audio for a chat message              |
| GET    | `/v1/user-memories`                | List your memories                           |
| GET    | `/v1/user-memories/{id}`           | Get a memory                                 |
| POST   | `/v1/user-memories`                | Create a memory                              |
| PATCH  | `/v1/user-memories/{id}`           | Update a memory                              |
| DELETE | `/v1/user-memories/{id}`           | Delete a memory                              |
| GET    | `/v1/organization-rules`           | List organization rules (admin)              |
| GET    | `/v1/organization-rules/{id}`      | Get an organization rule (admin)             |
| POST   | `/v1/organization-rules`           | Create an organization rule (admin)          |
| PATCH  | `/v1/organization-rules/{id}`      | Update an organization rule (admin)          |
| DELETE | `/v1/organization-rules/{id}`      | Delete an organization rule (admin)          |
| GET    | `/v1/admin/user-memories`          | List a member's memories (admin)             |
| POST   | `/v1/admin/user-memories`          | Create a memory for a member (admin)         |
| PATCH  | `/v1/admin/user-memories/{id}`     | Update a member's memory (admin)             |
| DELETE | `/v1/admin/user-memories/{id}`     | Delete a member's memory (admin)             |