> ## 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.

# Quickstart

> Send your first query with the Trellis API in under 5 minutes

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. 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](/authentication) for the derivation algorithm and reference snippets.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET https://api.trellis.sh/v1/integrations \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/chats/overview) for the full event taxonomy.

<Check>
  You've successfully sent your first query to the Trellis API.
</Check>

## Next steps

<CardGroup cols={2}>
  <Card title="Streaming Responses" icon="bolt" href="/api-reference/chats/overview">
    Learn how to handle SSE events in your application.
  </Card>

  <Card title="Saved Queries" icon="bookmark" href="/api-reference/queries/list-queries">
    Save and reuse common queries across your organization.
  </Card>

  <Card title="Response Feedback" icon="thumbs-up" href="/api-reference/chats/message-feedback">
    Collect user feedback on AI responses.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore all available endpoints.
  </Card>
</CardGroup>