> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v2 API Introduction

> Getting started with the TextQL v2 REST API

## Overview

The v2 API is a REST-native interface to the TextQL platform. It replaces the Connect-RPC protocol used by v1 with standard HTTP methods, path parameters, and JSON request/response bodies.

**What's different from v1:**

* Standard HTTP methods (`GET`, `POST`, `PATCH`, `DELETE`) instead of all-`POST`
* Resource IDs in URL paths (`/v2/playbooks/{id}`) instead of request bodies
* Query parameters for filtering and pagination
* Plain JSON errors (`{"error": {"code": "...", "message": "..."}}`)
* SSE streaming via `text/event-stream` instead of Connect-RPC server streaming
* No `Connect-Protocol-Version` header required

## Base URL

```
https://app.textql.com/v2
```

## Authentication

All requests require a Bearer token in the `Authorization` header:

```bash theme={null}
curl "https://app.textql.com/v2/connectors" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Get your API key at [app.textql.com/settings](https://app.textql.com/settings) → Configuration → API Keys.

## Quick Examples

### Create a chat

```bash theme={null}
curl -X POST "https://app.textql.com/v2/chats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the top 10 customers by revenue?", "connector_ids": [1]}'
```

### Stream a chat

```bash theme={null}
curl -X POST "https://app.textql.com/v2/chats/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Summarize last quarter sales"}' \
  --no-buffer
```

### List chats

```bash theme={null}
curl "https://app.textql.com/v2/chats?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### List playbooks

```bash theme={null}
curl "https://app.textql.com/v2/playbooks?limit=10&status_filter=deployed" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Error Handling

All errors return a consistent JSON envelope:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "playbook not found"
  }
}
```

| HTTP Status | Error Code            | Description                                         |
| ----------- | --------------------- | --------------------------------------------------- |
| 400         | `invalid_request`     | Malformed request or missing required fields        |
| 401         | `unauthenticated`     | Missing or invalid Bearer token                     |
| 403         | `permission_denied`   | Insufficient permissions for the requested resource |
| 404         | `not_found`           | Resource does not exist                             |
| 429         | `rate_limit_exceeded` | Too many requests                                   |
| 500         | `internal`            | Unexpected server error                             |
| 504         | `timeout`             | Request timed out                                   |

## Rate Limiting

All v2 endpoints are rate-limited per organization. When the limit is exceeded, the API returns a `429` status with the `rate_limit_exceeded` error code.