CosmiQ API Reference - StarTree Docs

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.

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/

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

CosmiQ Overview

What CosmiQ is, how Spaces work, and the deployment architecture behind these endpoints.

How to Use CosmiQ

Chat UI and MCP tool walkthroughs, and the Getting Started steps.

Security and Compliance

Read-only guarantees, data handling, and access controls.

​Authentication

​Endpoints

​POST /query

​POST /query/stream

​POST /api/bootstrap/space

​GET /api/spaces

​PATCH /api/spaces/

​POST /api/feedback

​GET /api/feedback/suggestions

​MCP tool

​Defaults reference

​Related documentation