Skip to main content
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 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: 
{
  "chats": [...],
  "projects": [...]
}

​
Error responses

Errors return a JSON object with a detail field: 
{
  "detail": "Chat not found"
}

​
HTTP status codes

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

MethodEndpointDescription
POST/v1/authenticateExchange API key for JWT token
GET/v1/modelsList available AI models
GET/v1/integrationsList database integrations
GET/v1/projectsList projects
GET/v1/projects/{id}Get a specific project
GET/v1/queriesList saved queries
GET/v1/queries/{id}Get a saved query
POST/v1/queriesCreate a saved query
PATCH/v1/queries/{id}Update a saved query
DELETE/v1/queries/{id}Delete a saved query
GET/v1/chatsList chats (paginated)
GET/v1/chats/{id}Get chat with messages
POST/v1/chats/createCreate an empty chat and obtain a chat_id
POST/v1/chatsSend message (SSE stream)
POST/v1/chats/uploadsUpload files to a chat
GET/v1/chats/{id}/uploadsList uploads for a chat
DELETE/v1/chats/uploads/{id}Delete an upload
PUT/v1/chats/{id}Update chat title
DELETE/v1/chatsDelete 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}/feedbackAdd message feedback
POST/v1/chats/followupsGet follow-up suggestions
POST/v1/voice/sessionsCreate a voice chat session
GET/v1/tts/messages/{id}/audioStream audio for a chat message
GET/v1/user-memoriesList your memories
GET/v1/user-memories/{id}Get a memory
POST/v1/user-memoriesCreate a memory
PATCH/v1/user-memories/{id}Update a memory
DELETE/v1/user-memories/{id}Delete a memory
GET/v1/organization-rulesList organization rules (admin)
GET/v1/organization-rules/{id}Get an organization rule (admin)
POST/v1/organization-rulesCreate 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-memoriesList a member’s memories (admin)
POST/v1/admin/user-memoriesCreate 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)