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

# CosmiQ API Reference

> REST API reference for CosmiQ — querying, Space management, and feedback.

CosmiQ exposes a documented REST API with interactive Swagger/OpenAPI docs (`/docs`) so you can embed it into any product or workflow. Every endpoint operates on the same Spaces and verified-query library used by the chat UI and the MCP tool.

## Authentication

All endpoints require a Bearer JWT. The chat UI's Chainlit session cookie (`access_token`) and the REST API share the same underlying session, so a token issued for one works for the other.

| Header | Required | Description |
| :- | :- | :- |
| `Authorization` | Yes | `Bearer <token>` |
| `Content-Type` | Yes | `application/json` |

## Endpoints

| Endpoint | Purpose |
| :- | :- |
| `POST /query` | Send a question, get an answer + SQL |
| `POST /query/stream` | Streaming (NDJSON) variant of `/query` |
| `POST /api/bootstrap/space` | Auto-generate a Space from Pinot tables |
| `GET /api/spaces` | List all Spaces |
| `PATCH /api/spaces/{id}` | Edit a Space's rules, tables, or verified queries |
| `POST /api/feedback` | Submit a thumbs up/down rating for an answer |
| `GET /api/feedback/suggestions` | See up-voted answers eligible for promotion to verified queries |

### POST /query

Ask a question against a Space and get back a complete answer — natural-language response, the generated SQL, and execution metadata.

```bash theme={null}
curl -X POST "https://<cosmiq-host>/query" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What were our top 5 customers by AWS spend last month?",
    "space": "aws-cost"
  }'
```

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `question` | string | Yes | The natural-language question to answer |
| `space` | string | No | The Space to answer within. Defaults to the caller's default Space if omitted. |

### POST /query/stream

Identical inputs to `POST /query`, but returns newline-delimited JSON (NDJSON) so the answer can be streamed token-by-token — the same mechanism the chat UI uses.

### POST /api/bootstrap/space

Probes a set of Pinot tables (schema, config, and a sample of live data) and drafts a first-pass Space: column descriptions, synonyms, inferred relationships, business rules tagged by confidence, and a handful of starter verified queries. Uses **Claude Opus** by default for the generation step. The result is a draft — review it via `PATCH /api/spaces/{id}` before relying on it.

### GET /api/spaces

Lists all Spaces visible to the authenticated principal.

### PATCH /api/spaces/{id}

Edits an existing Space's tables, business rules, relationships, query policy (including `do_not_use` columns and row/timeout limits), or verified queries.

### POST /api/feedback

Records a 👍/👎 rating for a specific answer. Highly-rated answers with working SQL are surfaced by `GET /api/feedback/suggestions` as candidates for promotion into the Space's verified-query library.

### GET /api/feedback/suggestions

Returns up-voted answers that are good candidates to promote into a Space's verified-query library.

## MCP tool

CosmiQ also exposes a `text_to_sql` MCP tool that wraps the same agent used by `POST /query`. See [How to Use CosmiQ](https://docs.startree.ai/corecapabilities/ai/cosmiq/usage.md#how-to-use-it) for setup.

***

## Defaults reference

These govern query and agent behavior across all access methods (chat UI, MCP tool, REST API). All settings except the models are configurable per Space via its query policy.

| Setting | Default | What it controls |
| :- | :- | :- |
| Chat model | Claude Sonnet | Fast answers for interactive chat |
| Bootstrap model | Claude Opus | More accurate Space generation |
| Max agent turns | 15 | Safety ceiling per question; most answers take 2–4 turns |
| Query timeout | 240 s | Per-query watchdog |
| Max rows returned | 50,000 | Per-Space policy; stops accidental full-table scans |
| Space context cache | 300 s | Amortizes load and render cost across repeat questions |
| Session lifetime | 8 hours | Auth0 session cookie |

***

## Related documentation

> **[CosmiQ Overview](https://docs.startree.ai/corecapabilities/ai/cosmiq/overview.md)**
>
> What CosmiQ is, how Spaces work, and the deployment architecture behind these endpoints.

> **[How to Use CosmiQ](https://docs.startree.ai/corecapabilities/ai/cosmiq/usage.md)**
>
> Chat UI and MCP tool walkthroughs, and the Getting Started steps.

> **[Security and Compliance](https://docs.startree.ai/corecapabilities/ai/cosmiq/security-and-compliance.md)**
>
> Read-only guarantees, data handling, and access controls.


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