Base URL
https://api.polaris.example.com/v1
All routes use JSON. Pass a bearer token to log in.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /datasets |
List datasets you can read |
| GET | /datasets/{id} |
Get one dataset's metadata |
| POST | /datasets/{id}/queries |
Run a query on a dataset |
| GET | /queries/{id} |
Poll a query for results |
| DELETE | /queries/{id} |
Cancel a running query |
Example: submit a query
curl -X POST \
-H "Authorization: Bearer $POLARIS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"sql": "select count(*) from events"}' \
https://api.polaris.example.com/v1/datasets/my-dataset/queries
Response:
{
"query_id": "q_01HZ2K9X8R7Y6V5T4S3R2Q1P0",
"status": "running",
"submitted_at": "2026-04-16T09:30:00Z"
}
Error codes
| Code | Meaning |
|---|---|
| 400 | Bad JSON, bad SQL, or missing field |
| 401 | Missing or expired token |
| 403 | Token valid but no access to this dataset |
| 404 | Dataset or query ID not found |
| 429 | Rate limit hit — see Retry-After header |
| 500 | Server error — please report it |