Quickstart - Trellis API

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 over the per-agent WebSocket.

Prerequisites

Before you begin, you’ll need:

A Trellis API key (contact your admin or Trellis support)
Your organization’s HMAC secret, kept on your backend
Your organization’s assigned agent UUID, supplied by Trellis and stored in configuration
A database integration configured in your Trellis organization

Keep the base hostname configurable so moving between environments is a configuration change.

Step 1: Authenticate

Exchange your API key for a JWT token. Each call needs both the user’s email and a user_key — an HMAC-derived value your backend computes from the shared secret Trellis issued you. See Authentication for the derivation algorithm and reference snippets.

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", "user_key": "your_computed_user_key"}'

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": "11111111-1111-4111-8111-111111111111",
      "display_name": "SQL Server Analytics",
      "type": "sqlserverdb"
    }
  ]
}

Note the id of the integration you want to query. Also call GET /v1/agents and confirm that your organization’s assigned agent UUID appears in the response. An organization may have a single published, org-scoped agent whose name and is_trellis_default flag are historical metadata; clients must match the configured id exactly rather than selecting by name, order, or flag.

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": "11111111-1111-4111-8111-111111111111"
  }'

Response:

{
  "id": "22222222-2222-4222-8222-222222222222",
  "organization_id": "20000000-0000-4000-8000-000000000001",
  "member_id": "33333333-3333-4333-8333-333333333333",
  "agent_id": "44444444-4444-4444-8444-444444444444",
  "title": "First query",
  "created_at": "2026-04-29T18:00:00+00:00"
}

Save the id as the chat_id. Verify that the returned agent_id exactly matches your configured agent UUID before opening the WebSocket. A mismatch means the chat is bound to a different agent: stop and contact Trellis rather than silently connecting to whichever agent is marked default.

Step 4: Send a query

Chat turns stream over the per-agent WebSocket endpoint at wss://api.trellis.sh/v1/agents/{agent_id}/chats/ws. Connect (authenticating on the upgrade), send a send_message frame, and read the streamed event frames. Every turn frame is wrapped in a durable envelope — read frame["event"] and frame["data"]:

import asyncio
import json
import os
import uuid
import websockets

AGENT_ID = os.environ["TRELLIS_AGENT_ID"]       # supplied by Trellis
CHAT_ID = "22222222-2222-4222-8222-222222222222"   # from Step 3

async def ask():
    async with websockets.connect(
        f"wss://api.trellis.sh/v1/agents/{AGENT_ID}/chats/ws",
        additional_headers=[("Authorization", "Bearer YOUR_TOKEN")],
    ) as ws:
        # First frame is the bare `authenticated` handshake.
        print(json.loads(await ws.recv()))

        await ws.send(json.dumps({
            "action": "send_message",
            "message": "How many orders were placed last month?",
            "chat_id": CHAT_ID,
            "integration_id": "11111111-1111-4111-8111-111111111111",
            "client_request_id": str(uuid.uuid4()),
        }))

        turn_id = None
        async for raw in ws:
            frame = json.loads(raw)
            if frame["event"] == "heartbeat":
                continue
            if frame["event"] == "turn_accepted":
                turn_id = frame["data"]["turn_id"]  # persist for interrupt/resume
            print(frame["event"], frame["data"])
            if (frame["event"] == "error" and frame.get("turn_id") is None) or (
                turn_id is not None
                and frame.get("turn_id") == turn_id
                and frame["event"] in ("message", "error", "interrupted")
            ):
                break

asyncio.run(ask())

Streamed frames (excerpt):

{"chat_id": "22222222-2222-4222-8222-222222222222", "turn_id": "55555555-5555-4555-8555-555555555555", "seq": 0, "event": "turn_accepted", "data": {"turn_id": "55555555-5555-4555-8555-555555555555", "chat_id": "22222222-2222-4222-8222-222222222222", "user_message_id": "66666666-6666-4666-8666-666666666666", "status": "in_progress"}}
{"chat_id": "22222222-2222-4222-8222-222222222222", "turn_id": "55555555-5555-4555-8555-555555555555", "seq": 1, "event": "chat_metadata", "data": {"id": "22222222-2222-4222-8222-222222222222", "user_message_id": "66666666-6666-4666-8666-666666666666"}}
{"chat_id": "22222222-2222-4222-8222-222222222222", "turn_id": "55555555-5555-4555-8555-555555555555", "seq": 2, "event": "processing", "data": {"status": "starting"}}
{"chat_id": "22222222-2222-4222-8222-222222222222", "turn_id": "55555555-5555-4555-8555-555555555555", "seq": 3, "event": "tool_call", "data": {"tool": "data_analytics__execute_sql", "args": {"sql": "SELECT COUNT(*) FROM dbo.Orders WHERE ..."}, "tool_call_id": "tc_1"}}
{"chat_id": "22222222-2222-4222-8222-222222222222", "turn_id": "55555555-5555-4555-8555-555555555555", "seq": 4, "event": "tool_result", "data": {"tool": "data_analytics__execute_sql", "tool_call_id": "tc_1", "output": {"kind": "table", "columns": [{"name": "count", "type_hint": "number"}], "rows": [[1523]], "row_count": 1, "truncated": false}}}
{"chat_id": "22222222-2222-4222-8222-222222222222", "turn_id": "55555555-5555-4555-8555-555555555555", "seq": 5, "event": "text_delta", "data": {"content": "There were "}}
{"chat_id": "22222222-2222-4222-8222-222222222222", "turn_id": "55555555-5555-4555-8555-555555555555", "seq": 6, "event": "text_delta", "data": {"content": "1,523 orders placed last month."}}
{"chat_id": "22222222-2222-4222-8222-222222222222", "turn_id": "55555555-5555-4555-8555-555555555555", "seq": 7, "event": "message", "data": {"id": "77777777-7777-4777-8777-777777777777", "content": "There were 1,523 orders placed last month.", "timestamp": "2026-08-08T18:00:03+00:00"}}

See the WebSocket endpoint for the full protocol — envelope, interrupt, resume, and errors — and Structured Output for handling charts, tables, and panels.

You’ve successfully sent your first query to the Trellis API.

Next steps

Streaming Responses

Learn how to stream chat turns over WebSocket — envelope, interrupt, resume.

Structured Output

Handle charts, tables, and typed panels from the chat stream.

Response Feedback

Collect user feedback on AI responses.

API Reference

Explore all available endpoints.

​Prerequisites

​Step 1: Authenticate

​Step 2: List available integrations

​Step 3: Create a chat

​Step 4: Send a query

​Next steps

Streaming Responses

Structured Output

Response Feedback

API Reference

Prerequisites

Step 1: Authenticate

Step 2: List available integrations

Step 3: Create a chat

Step 4: Send a query

Next steps