API Reference

The Querri Public API v1 provides programmatic access to projects, dashboards, data sources, users, access policies, and more. All endpoints require qk_ API key authentication — see Authentication.

Interactive Documentation

The full interactive API reference with request/response schemas is available at your Querri instance:

Swagger UI: /api/v1/docs
ReDoc: /api/v1/redoc
OpenAPI JSON: /api/v1/openapi.json — import into Postman, Insomnia, or any OpenAPI client

For local development, these are at http://localhost/api/v1/docs and http://localhost/api/v1/redoc.

Base URL

https://app.querri.com/api/v1

Required Headers

Authorization: Bearer qk_live_...
X-Tenant-ID: org_...

Error Format

All errors follow a consistent structure:

{
  "error": {
    "type": "not_found_error",
    "code": "project_not_found",
    "message": "No project with ID 'proj_abc123'"
  }
}

Error types: authentication_error, permission_error, invalid_request_error, not_found_error, rate_limit_error, api_error.

Users

Manage organization members. Users can be created with an external_id for idempotent upsert via your own user system.

Method	Endpoint	Description	Scope
`POST`	`/users`	Create a new user	`admin:users:write`
`GET`	`/users`	List users (supports `?external_id=` filter)	`admin:users:read`
`GET`	`/users/{user_id}`	Get user by ID	`admin:users:read`
`PUT`	`/users/external/{external_id}`	Get or create user by external ID (idempotent)	`admin:users:write`
`PATCH`	`/users/{user_id}`	Update user role or profile	`admin:users:write`
`DELETE`	`/users/{user_id}`	Delete a user	`admin:users:write`

Projects

Create, manage, and execute data analysis projects.

Method	Endpoint	Description	Scope
`GET`	`/projects`	List projects	`admin:projects:read`
`POST`	`/projects`	Create a project	`admin:projects:write`
`GET`	`/projects/{project_id}`	Get project details	`admin:projects:read`
`PUT`	`/projects/{project_id}`	Update project metadata	`admin:projects:write`
`DELETE`	`/projects/{project_id}`	Delete a project	`admin:projects:write`
`POST`	`/projects/{project_id}/run`	Execute a project	`admin:projects:write`
`GET`	`/projects/{project_id}/run/status`	Check execution status	`admin:projects:read`
`POST`	`/projects/{project_id}/run/cancel`	Cancel execution	`admin:projects:write`
`GET`	`/projects/{project_id}/steps`	List project steps	`admin:projects:read`
`GET`	`/projects/{project_id}/steps/{step_id}/data`	Get step result data (paginated, RLS-enforced)	`admin:projects:read`

Chats

AI chat within projects. The stream endpoint returns Server-Sent Events (SSE).

Method	Endpoint	Description	Scope
`POST`	`/projects/{project_id}/chats`	Create a new chat	`admin:projects:write`
`GET`	`/projects/{project_id}/chats`	List chats for a project	`admin:projects:read`
`GET`	`/projects/{project_id}/chats/{chat_id}`	Get chat messages	`admin:projects:read`
`DELETE`	`/projects/{project_id}/chats/{chat_id}`	Delete a chat	`admin:projects:write`
`POST`	`/projects/{project_id}/chats/{chat_id}/stream`	Send message and stream AI response (SSE)	`admin:projects:write`
`GET`	`/projects/{project_id}/chats/{chat_id}/stream`	Resume an active stream	`admin:projects:read`
`POST`	`/projects/{project_id}/chats/{chat_id}/cancel`	Cancel an active stream	`admin:projects:write`

Chat Streaming

The POST .../stream endpoint returns a text/event-stream response. Events use the Vercel AI SDK format:

0:"Hello "
0:"world"
e:{"finishReason":"stop"}
d:{"finishReason":"stop"}

0: prefix — text chunk (JSON-encoded string)
e: prefix — error event
d: prefix — done signal

Dashboards

Create and manage dashboards. Includes template import/export.

Method	Endpoint	Description	Scope
`POST`	`/dashboards`	Create a dashboard	`admin:dashboards:write`
`GET`	`/dashboards`	List dashboards	`admin:dashboards:read`
`GET`	`/dashboards/{dashboard_id}`	Get dashboard details	`admin:dashboards:read`
`PATCH`	`/dashboards/{dashboard_id}`	Update dashboard metadata	`admin:dashboards:write`
`DELETE`	`/dashboards/{dashboard_id}`	Delete a dashboard	`admin:dashboards:write`
`POST`	`/dashboards/{dashboard_id}/refresh`	Trigger dashboard refresh	`admin:dashboards:write`
`GET`	`/dashboards/{dashboard_id}/refresh/status`	Check refresh status	`admin:dashboards:read`
`POST`	`/dashboards/from-template`	Create dashboard from template	`admin:dashboards:write`
`POST`	`/dashboards/{dashboard_id}/export-template`	Export dashboard as template	`admin:dashboards:read`

Access Policies

Row-level security (RLS) policies control which data sources and rows users can see.

Method	Endpoint	Description	Scope
`POST`	`/access/policies`	Create an access policy	`admin:policies:write`
`GET`	`/access/policies`	List policies (supports `?name=` filter)	`admin:policies:read`
`GET`	`/access/policies/{policy_id}`	Get policy details	`admin:policies:read`
`PATCH`	`/access/policies/{policy_id}`	Update policy rules	`admin:policies:write`
`DELETE`	`/access/policies/{policy_id}`	Delete a policy	`admin:policies:write`
`POST`	`/access/policies/{policy_id}/users`	Assign users to policy	`admin:policies:write`
`DELETE`	`/access/policies/{policy_id}/users/{user_id}`	Remove user from policy	`admin:policies:write`
`POST`	`/access/resolve`	Preview resolved access for a user + source	`admin:policies:read`
`GET`	`/access/columns`	Discover filterable columns for a source	`admin:policies:read`

Data

Query data sources directly. Results respect row-level security.

Method	Endpoint	Description	Scope
`GET`	`/data/sources`	List available data sources	`data:read`
`GET`	`/data/sources/{source_id}`	Get source details and schema	`data:read`
`GET`	`/data/sources/{source_id}/data`	Read source data (paginated)	`data:read`
`POST`	`/data/query`	Execute SQL query against a source	`data:read`

Embed Sessions

Create short-lived session tokens for embedding Querri views in iframes.

Method	Endpoint	Description	Scope
`POST`	`/embed/sessions`	Create an embed session	`embed:session:create`
`POST`	`/embed/sessions/refresh`	Refresh an expiring session	`embed:session:create`
`GET`	`/embed/sessions`	List active sessions	`embed:session:create`
`DELETE`	`/embed/sessions/{session_id}`	Revoke a session	`embed:session:create`

Files

Upload and manage files (CSV, Excel, JSON, etc.) for use as data sources.

Method	Endpoint	Description	Scope
`GET`	`/files`	List uploaded files	`admin:files:read`
`GET`	`/files/{file_id}`	Get file metadata	`admin:files:read`
`POST`	`/files/upload`	Upload a file	`admin:files:write`
`DELETE`	`/files/{file_id}`	Delete a file	`admin:files:write`

Sources & Connectors

Manage data source connections (databases, SaaS apps, files).

Method	Endpoint	Description	Scope
`GET`	`/connectors`	List available connector types	`admin:sources:read`
`GET`	`/sources`	List data sources	`admin:sources:read`
`POST`	`/sources`	Create a data source	`admin:sources:write`
`PATCH`	`/sources/{source_id}`	Update source configuration	`admin:sources:write`
`DELETE`	`/sources/{source_id}`	Delete a data source	`admin:sources:write`
`POST`	`/sources/{source_id}/sync`	Trigger source sync	`admin:sources:write`

API Keys

Manage API keys programmatically. Requires the admin:keys:manage scope.

Method	Endpoint	Description	Scope
`POST`	`/keys`	Create a new API key	`admin:keys:manage`
`GET`	`/keys`	List API keys	`admin:keys:manage`
`GET`	`/keys/{key_id}`	Get key details	`admin:keys:manage`
`DELETE`	`/keys/{key_id}`	Revoke a key	`admin:keys:manage`

Share projects and dashboards with other users in your organization.

Method	Endpoint	Description	Scope
`POST`	`/projects/{project_id}/shares`	Share a project with a user	`admin:permissions:write`
`GET`	`/projects/{project_id}/shares`	List project shares	`admin:permissions:read`
`DELETE`	`/projects/{project_id}/shares/{user_id}`	Revoke project share	`admin:permissions:write`
`POST`	`/dashboards/{dashboard_id}/shares`	Share a dashboard with a user	`admin:permissions:write`
`GET`	`/dashboards/{dashboard_id}/shares`	List dashboard shares	`admin:permissions:read`
`DELETE`	`/dashboards/{dashboard_id}/shares/{user_id}`	Revoke dashboard share	`admin:permissions:write`

Usage

View organization and per-user usage metrics.

Method	Endpoint	Description	Scope
`GET`	`/usage`	Organization usage summary	`admin:usage:read`
`GET`	`/usage/users/{user_id}`	Per-user usage metrics	`admin:usage:read`

Audit

Query the audit log for security and compliance.

Method	Endpoint	Description	Scope
`GET`	`/audit/events`	Query audit log events	`admin:audit:read`

Pagination

List endpoints return paginated results:

{
  "data": [...],
  "total": 142,
  "page": 1,
  "page_size": 50,
  "has_more": true
}

Use ?page=2&page_size=50 to navigate. Maximum page size is 200.