API reference

The Trellis Public API — a REST + WebSocket surface spanning chats, saved queries, datasources, voice, and memories.

Base URL

https://api.trellis.sh

Keep this host configurable. Trellis supplies a separate pre-production host during onboarding for build-and-test work.

Authentication

All endpoints except /, /v1/health, and /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

Request bodies are JSON with Content-Type: application/json unless an endpoint documents multipart upload data.
Live chat streaming uses the WebSocket endpoint. Detached clients can submit a durable turn over REST and poll its status.

Response format

Most responses return JSON. Artifact payloads, message audio, and similar download endpoints return their documented binary content types.

{
  "chats": [...],
  "projects": [...]
}

Error responses

HTTP error bodies are not uniform. Handle these JSON shapes:

{"detail": "Chat not found"}
{"detail": [{"loc": ["body", "field"], "msg": "..."}]}
{"detail": {"code": "OPEN_CHAT_CAP", "current_count": 500, "cap": 500}}
{"code": "RATE_LIMIT", "retry_after_seconds": 13}

The 429 shape has no detail key and also includes a Retry-After header. An unhandled server error can be plain text, so inspect Content-Type before parsing a 5xx body as JSON. Errors on the chat WebSocket arrive as error frames instead. Terminal turn errors normalize to {error, code, retryable, debug_id}; validation and other pre-turn errors may omit some of those fields. Branch on code when present and treat the human-readable message as non-contractual.

HTTP status codes

Code	Description
200	Success
201	Created
202	Accepted - asynchronous work was accepted
204	No Content - success with no response body
400	Bad request - invalid parameters
401	Unauthorized - missing or invalid token
403	Forbidden - insufficient permission
404	Not found - resource doesn’t exist
409	Conflict - idempotency, running-turn, or resource-cap conflict
422	Validation error - request shape failed validation
429	Too many requests - rate limit exceeded; check `Retry-After`
500	Internal server error
502	Bad gateway - an upstream dependency failed
503	Service unavailable - a required service is not configured or available

Rate limits

Limits on authenticated endpoints are keyed by member_id; re-authenticating does not reset them. The authentication endpoint has a separate API-key budget.

Operation	Limit
Authenticate	60 per minute per API key
WebSocket send/edit and REST turn submission, shared across both transports	10 per minute and 3 per 10 seconds per member
Active external WebSocket connections	3 per member
Create chat	20 per minute per member
Upload chat files	30 per minute per member
Generate follow-up suggestions	10 per minute and 5 per 10 seconds per member
Transcribe audio	20 per minute per member

HTTP limits return 429 with Retry-After; WebSocket submission limits return an error frame with code: "RATE_LIMIT" and retry_after_seconds.

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
GET	`/`	Service liveness
GET	`/v1/health`	Health check
POST	`/v1/authenticate`	Exchange API key for JWT token
GET	`/v1/models`	List available AI models
GET	`/v1/agents`	List your published agents (for the WebSocket URL)
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
GET	`/v1/chats/{id}/messages/{id}`	Get a single message
POST	`/v1/chats/create`	Create an empty chat and obtain a `chat_id`
WS	`/v1/agents/{agent_id}/chats/ws`	Stream a chat turn — send, edit, interrupt, resume (WebSocket)
POST	`/v1/agents/{agent_id}/chats/{chat_id}/turns`	Submit a durable turn without a socket
GET	`/v1/agents/{agent_id}/chats/{chat_id}/turns/{turn_id}`	Poll durable turn status
POST	`/v1/agents/{agent_id}/chats/{chat_id}/turns/{turn_id}/cancel`	Request durable turn cancellation
GET	`/v1/chats/{id}/panels/{id}`	Fetch a typed panel
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/messages/{id}/feedback`	Add message feedback
POST	`/v1/chats/followups`	Get follow-up suggestions
GET	`/v1/artifacts/{id}`	Get artifact status
GET	`/v1/artifacts/{id}/payload`	Fetch artifact payload bytes
GET	`/v1/jobs/{id}`	Poll a background job
POST	`/v1/jobs/{id}/cancel`	Cancel a background job
POST	`/v1/voice/sessions`	Create a voice chat session
POST	`/v1/voice/timing`	Report voice startup timing
POST	`/v1/audio/transcribe`	Transcribe an audio clip
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
POST	`/v1/user-memories/reorder`	Reorder your memories
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)
POST	`/v1/organization-rules/reorder`	Reorder organization rules (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)
POST	`/v1/admin/user-memories/reorder`	Reorder a member’s memories (admin)

Overview

Authentication

Agents

Datasources

Saved Queries

Models

Chats

Artifacts

Jobs

Voice

Audio

User Memories

Organization Rules

Admin

Base URL

Authentication

Request format

Response format

Error responses

HTTP status codes

Rate limits

Endpoint summary

​Base URL

​Authentication

​Request format

​Response format

​Error responses

​HTTP status codes

​Rate limits

​Pagination

​Endpoint summary

Base URL

Authentication

Request format

Response format

Error responses

HTTP status codes

Rate limits

Pagination

Endpoint summary