API Reference

The Querri Public API v1 provides programmatic access to projects, dashboards, data sources, users, access policies, and more. Endpoints accept qk_ API keys (the primary method for server-to-server integrations), JWT bearer tokens (for user-context calls), or session cookies with CSRF (for browser apps already logged in) — see Authentication for details.

The Python SDK (pip install querri) and querri CLI (pip install "querri[cli]") cover most of these endpoints with typed clients and one-line commands; reach for them before hand-rolling HTTP requests.

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

For API key authentication (the default for integrations):

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

For JWT bearer authentication, send only Authorization: Bearer ey... — the org_id is read from the token. For full details and the cookie-based flow, see Authentication.

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

Read and write data sources directly. Read results respect row-level security. See the Data API guide for detailed examples and integration patterns.

Method	Endpoint	Description	Scope
GET	/sources	List available data sources	data:read
GET	/sources/{source_id}	Get source details and schema	data:read
GET	/sources/{source_id}/data	Read source data (paginated)	data:read
POST	/sources/{source_id}/query	Execute SQL query against a source	data:read
POST	/sources	Create a source with inline data (body: {name, rows})	data:write
POST	/sources/{source_id}/rows	Append rows to a source	data:write
PUT	/sources/{source_id}/data	Replace all data in a source	data:write
DELETE	/sources/{source_id}	Delete a source and its data	data:write

Note

The /sources paths are shared with the Sources & Connectors surface below. The Data API and the Sources & Connectors API hit the same routes but are distinguished by request body shape and scope: POST /sources with {name, rows} + data:write creates an inline-data source, while POST /sources with {name, connector_id, config} + admin:sources:write creates a connector-backed source.

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

Sharing

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.