Skip to main content
This guide walks you through authenticating and sending your first natural language query to a database.

​
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: 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?",
    "integration_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
Streamed response: 
event: chat_metadata
data: {"id": "chat_abc123"}

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

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

event: message
data: {"content": "There were 1,523 orders placed last month.", "id": "msg_xyz789"}
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.