v2 API Introduction

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:

curl "https://app.textql.com/v2/connectors" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your API key at app.textql.com/settings → Configuration → API Keys. Keys can also be minted programmatically with 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). Revoke keys with Revoke API Key.

Quick Examples

Create a chat

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

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

curl "https://app.textql.com/v2/chats?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

List playbooks

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:

{
  "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.

Getting Started

API Keys

Members

Roles

Chat

Connectors

Playbooks

Dashboards

Sandcastles

Changes

Overview

Base URL

Authentication

Quick Examples

Create a chat

Stream a chat

List chats

List playbooks

Error Handling

Rate Limiting

​Overview

​Base URL

​Authentication

​Quick Examples

​Create a chat

​Stream a chat

​List chats

​List playbooks

​Error Handling

​Rate Limiting

Overview

Base URL

Authentication

Quick Examples

Create a chat

Stream a chat

List chats

List playbooks

Error Handling

Rate Limiting