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

Keys can also be minted programmatically with
[Create API Key](/api-reference/v2/api-keys/create-api-key): scope a key to
specific roles, give it an expiry, and attach `clientId` metadata that TQL
row-level security reads per request — the pattern for embedding and
multi-tenant API access (see the
[embedding guide](/core/guides/embedding-ana#programmatic-role-scoping)).
Revoke keys with [Revoke API Key](/api-reference/v2/api-keys/revoke-api-key).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.