API Reference

Explore the complete API documentation for That Is A Q. Everything you need to integrate, build, and scale with our platform.

https://api.thatisaq.com/v3

Authentication

That Is A Q uses API keys to authenticate requests. Keep your keys secure and never expose them in client-side code. You can manage your API keys in the developer dashboard.

⚠️

Security Notice Treat your API keys like passwords. Anyone with your key can access your resources. Use environment variables to store keys securely.

API Key Types

🔑 Secret Key

Full access to all resources. Use server-side only. Prefix: sk_live_

🔒 Restricted Key

Limited scope and permissions. Use for specific endpoints. Prefix: rk_live_

cURL

curl https://api.thatisaq.com/v3/q-objects \
  -H "Authorization: Bearer sk_live_abc123def456" \
  -H "Content-Type: application/json"

JavaScript

const axios = require('axios');

const response = await axios.get('https://api.thatisaq.com/v3/q-objects', {
  headers: {
    'Authorization': `Bearer ${process.env.Q_API_KEY}`,
    'Content-Type': 'application/json',
    'X-Q-Request-ID': crypto.randomUUID(),
  }
});

Python

import requests

headers = {
    "Authorization": f"Bearer {os.environ['Q_API_KEY']}",
    "Content-Type": "application/json",
    "X-Q-Request-ID": uuid4().__str__(),
}

response = requests.get("https://api.thatisaq.com/v3/q-objects", headers=headers)

ℹ️

Custom Headers Always include X-Q-Request-ID for request tracing. We also recommend setting Idempotency-Key for POST/PUT requests.

Rate Limiting

API requests are rate limited to ensure fair usage. When you exceed the limit, you'll receive a 429 Too Many Requests response.

Rate Limits by Plan

1,000

req / min

50,000

req / day

∞

burst capacity

Rate limit headers are included in every response:

Response Headers

X-RateLimit-Limit:       1000
X-RateLimit-Remaining:   847
X-RateLimit-Reset:       1709251200
Retry-After:             32

Error Handling

The API uses conventional HTTP status codes to indicate success or failure. Error responses include a JSON body with details about what went wrong.

Error Response

{
  "error": {
    "code": "invalid_request_error",
    "message": "The 'name' field is required and must be a string",
    "param": "name",
    "type": "validation_error",
    "request_id": "req_Qx7k2mP9wRn"
  }
}

HTTP Status Codes

200 OK — The request succeeded

201 Created — Resource successfully created

400 Bad Request — Malformed request or invalid params

401 Unauthorized — Missing or invalid API key

403 Forbidden — Insufficient permissions

404 Not Found — Resource does not exist

429 Too Many Requests — Rate limit exceeded

500 Server Error — Something went wrong on our end

503 Service Unavailable — Temporary maintenance

API Versioning

The current stable API version is v3. We use URL-based versioning to ensure backward compatibility and smooth upgrades.

📌

Best Practice Pin your API version explicitly. Avoid using the latest alias in production to avoid unexpected breaking changes.

Q Objects

A Q Object is the fundamental building block of the That Is A Q platform. Each Q represents a unique, queryable entity that can be created, retrieved, updated, and deleted via the API.

GET /q-objects List all Q objects Stable

Retrieves a paginated list of all Q objects in your account. By default, returns the most recent Q objects first.

Query Parameters

Parameter	Type	Required	Description
limit	integer	Optional	Number of results to return (1–100, default: 20)
cursor	string	Optional	Pagination cursor for fetching the next page
sort	string	Optional	Sort order: `created_at`, `updated_at`, `name`
status	string	Optional	Filter by status: `active`, `archived`, `draft`

cURL

curl "https://api.thatisaq.com/v3/q-objects?limit=10&sort=created_at" \
  -H "Authorization: Bearer sk_live_abc123"

Response (200 OK)

{
  "data": [
    {
      "id": "q_obj_9fK2mP7xRn4L",
      "name": "Quarterly Revenue Analysis",
      "status": "active",
      "type": "analytics",
      "metadata": { "region": "us-east" },
      "created_at": "2025-01-15T09:30:00Z",
      "updated_at": "2025-01-20T14:22:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InFfb2Jq...",
  "total_count": 1847
}

POST /q-objects Create a new Q object Stable

Creates a new Q object in your account. You can specify custom metadata, tags, and configuration options.

Request Body

Property	Type	Required	Description
name	string	Required	Human-readable name for the Q object (1–128 chars)
type	string	Required	Object type: `analytics`, `query`, `pipeline`, `dashboard`
description	string	Optional	Detailed description (max 2048 chars)
metadata	object	Optional	Custom key-value pairs (max 20 entries)
tags	array	Optional	List of tag strings for categorization (max 10)
config	object	Optional	Additional configuration for the Q object

cURL

curl -X POST https://api.thatisaq.com/v3/q-objects \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-12345" \
  -d '{
    "name": "Customer Churn Prediction",
    "type": "pipeline",
    "description": "ML pipeline for predicting customer churn",
    "metadata": { "team": "data-science", "priority": "high" },
    "tags": ["ml", "churn", "production"],
    "config": { "model": "xgboost", "version": "2.1" }
  }'

Response (201 Created)

{
  "id": "q_obj_7nM3pQ8wXk2R",
  "name": "Customer Churn Prediction",
  "type": "pipeline",
  "status": "draft",
  "description": "ML pipeline for predicting customer churn",
  "metadata": { "team": "data-science", "priority": "high" },
  "tags": ["ml", "churn", "production"],
  "config": { "model": "xgboost", "version": "2.1" },
  "created_at": "2025-01-22T11:45:00Z",
  "updated_at": "2025-01-22T11:45:00Z",
  "_links": {
    "self": "https://api.thatisaq.com/v3/q-objects/q_obj_7nM3pQ8wXk2R",
    "delete": "https://api.thatisaq.com/v3/q-objects/q_obj_7nM3pQ8wXk2R"
  }
}

GET /q-objects/{q_id} Retrieve a Q object Stable

Retrieves a single Q object by its unique ID. Returns the full object including all metadata and configuration.

cURL

curl https://api.thatisaq.com/v3/q-objects/q_obj_7nM3pQ8wXk2R \
  -H "Authorization: Bearer sk_live_abc123"

Response (200 OK)

{
  "id": "q_obj_7nM3pQ8wXk2R",
  "name": "Customer Churn Prediction",
  "type": "pipeline",
  "status": "active",
  "description": "ML pipeline for predicting customer churn",
  "metadata": { "team": "data-science", "priority": "high" },
  "tags": ["ml", "churn", "production"],
  "config": { "model": "xgboost", "version": "2.1" },
  "runs": { "total": 847, "last_run": "2025-01-21T08:15:00Z" },
  "created_at": "2025-01-22T11:45:00Z",
  "updated_at": "2025-01-22T14:30:00Z"
}

PUT /q-objects/{q_id} Update a Q object Stable

Updates an existing Q object. Only the fields you provide will be modified — omitting a field leaves it unchanged. Supports partial updates.

cURL

curl -X PUT https://api.thatisaq.com/v3/q-objects/q_obj_7nM3pQ8wXk2R \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Churn Prediction v2",
    "status": "active",
    "metadata": { "team": "data-science", "priority": "critical" }
  }'

Response (200 OK)

{
  "id": "q_obj_7nM3pQ8wXk2R",
  "name": "Customer Churn Prediction v2",
  "type": "pipeline",
  "status": "active",
  "metadata": { "team": "data-science", "priority": "critical" },
  "updated_at": "2025-01-23T09:12:00Z"
}

DELETE /q-objects/{q_id} Delete a Q object Stable

Permanently deletes a Q object and all associated data. This action is irreversible. Archived Q objects can be deleted after a 30-day grace period.

🗑️

Destructive Action This operation cannot be undone. Consider using the archive status instead of deleting if you need to recover data later.

cURL

curl -X DELETE https://api.thatisaq.com/v3/q-objects/q_obj_7nM3pQ8wXk2R \
  -H "Authorization: Bearer sk_live_abc123"

Response (204 No Content)

{}

POST /q-objects/search Search Q objects Beta

Performs full-text search across Q object names, descriptions, tags, and metadata. Supports faceted filtering and relevance scoring.

cURL

curl -X POST https://api.thatisaq.com/v3/q-objects/search \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "churn prediction",
    "filters": {
      "type": "pipeline",
      "status": "active",
      "tags": ["ml"]
    },
    "sort": "relevance",
    "limit": 10
  }'

Response (200 OK)

{
  "results": [
    {
      "object": { /* Q object */ },
      "score": 0.947,
      "highlights": ["...churn prediction model..."]
    }
  ],
  "total": 42,
  "facets": {
    "type": { "pipeline": 28, "analytics": 14 },
    "status": { "active": 35, "draft": 7 }
  }
}

Webhooks

Subscribe to events to receive real-time HTTP POST notifications when certain actions occur in your account.

Webhook Payload

{
  "id": "wh_3mK8pL2nQr5X",
  "type": "q_object.updated",
  "timestamp": "2025-01-23T10:15:00Z",
  "data": {
    "id": "q_obj_7nM3pQ8wXk2R",
    "previous_status": "draft",
    "current_status": "active",
    "updated_by": "user_abc123"
  }
}

🔐

Verification Each webhook includes an X-Q-Signature header. Verify it using your webhook secret to ensure authenticity.

Pagination

All list endpoints use cursor-based pagination. The response includes a has_more flag and next_cursor for fetching subsequent pages.

Example: Fetch Next Page

curl "https://api.thatisaq.com/v3/q-objects?cursor=eyJpZCI6InFfb2Jq...&limit=20" \
  -H "Authorization: Bearer sk_live_abc123"

Batch Operations

Perform multiple operations in a single request. Batch operations reduce network overhead and ensure atomicity across related resources.

cURL — Batch Update

curl -X POST https://api.thatisaq.com/v3/batch \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "method": "PUT",
        "path": "/q-objects/q_obj_7nM3pQ8wXk2R",
        "body": { "status": "archived" }
      },
      {
        "method": "PUT",
        "path": "/q-objects/q_obj_2mK9pR3wYn5S",
        "body": { "status": "archived" }
      }
    ]
  }'

Streaming New

Subscribe to real-time event streams using Server-Sent Events (SSE) for live data updates.

JavaScript — SSE Client

const eventSource = new EventSource(
  'https://api.thatisaq.com/v3/stream/events',
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Accept': 'text/event-stream'
    }
  }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data.data);
};

Schemas

Q Object Schema

Field	Type	Description
id	string	Unique identifier, prefixed with `q_obj_`
name	string	Human-readable name (1–128 characters)
type	string	Enum: `analytics`, `query`, `pipeline`, `dashboard`
status	string	Enum: `active`, `draft`, `archived`
metadata	object	Custom key-value pairs (max 20 entries, strings only)
tags	array<string>	Categorization tags (max 10)
config	object	Optional configuration object specific to type
created_at	datetime	ISO 8601 timestamp of creation
updated_at	datetime	ISO 8601 timestamp of last modification

SDKs & Libraries

We offer official SDKs for popular languages. Community-maintained libraries are also available.

Installation

# npm
npm install @thatisaq/q-sdk

# pip
pip install thatis-aq

# go
go get github.com/thatisaq/q-go

# ruby
gem install thatis_aq

JavaScript Quick Start

import { QClient } from '@thatisaq/q-sdk';

const q = new QClient(process.env.Q_API_KEY);

const qObj = await q.qObjects.create({
  name: "My First Q",
  type: "pipeline",
  metadata: { "source": "api-reference" }
});

console.log(qObj.id); // q_obj_9fK2mP7xRn4L

Still have questions?

Contact Support · Discord Community · GitHub Issues