Skip to main content

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.

Five minutes from API key to your first streamed answer. The flow is four steps: exchange your API key for a JWT, list your integrations, create a chat, and send a natural-language query.

​
Prerequisites

Before you begin, you’ll need:
  • A Trellis API key (contact your admin or Trellis support)
  • A database integration configured in your Trellis organization

​
Step 1: Authenticate

Exchange your API key for a JWT token: 
curl -X POST https://api.trellis.sh/v1/authenticate \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
Save the token from the response—you’ll use it for all subsequent requests.

​
Step 2: List available integrations

Find out which database integrations are available: 
curl -X GET https://api.trellis.sh/v1/integrations \
  -H "Authorization: Bearer YOUR_TOKEN"
Response: 
{
  "integrations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "display_name": "Production Analytics DB",
      "type": "database"
    }
  ]
}
Note the id of the integration you want to query.

​
Step 3: Create a chat

Every conversation starts with a chat_id. Create one before sending a message: 
curl -X POST https://api.trellis.sh/v1/chats/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "First query",
    "integration_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
Response: 
{
  "id": "chat_abc123",
  "organization_id": "org_abc123",
  "member_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "First query",
  "created_at": "2026-04-29T18:00:00+00:00"
}
Save the id — you’ll pass it as chat_id on every message in this conversation.

​
Step 4: Send a query

Now you’re ready to ask a question. The response streams back using Server-Sent Events (SSE): 
curl -X POST https://api.trellis.sh/v1/chats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "How many orders were placed last month?",
    "chat_id": "chat_abc123",
    "integration_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
Streamed response (excerpt): 
event: chat_metadata
data: {"id": "chat_abc123"}

event: processing
data: {"status": "thinking"}

event: tool_call
data: {"tool": "execute_sql", "args": {"query": "SELECT COUNT(*) ..."}}

event: tool_result
data: {"row_count": 1, "rows": [[1523]]}

event: text_delta
data: {"content": "There were "}

event: text_delta
data: {"content": "1,523 orders"}

event: text_delta
data: {"content": " placed last month."}

event: final
data: {"id": "msg_xyz789", "content": "There were 1,523 orders placed last month."}
See Chats overview for the full event taxonomy.
You’ve successfully sent your first query to the Trellis API.

​
Next steps

Streaming Responses

Learn how to handle SSE events in your application.

Saved Queries

Save and reuse common queries across your organization.

Response Feedback

Collect user feedback on AI responses.

API Reference

Explore all available endpoints.