Core API Endpoints

This page catalogs the Thallus API endpoints organized by domain. All endpoints are prefixed with /api/v1 and return JSON unless otherwise noted. Authentication is required for most endpoints — see the Auth column for specifics.

Conventions

Authentication

Endpoints are marked with their required auth level:

None User Admin Superadmin

See API Authentication for details on JWT and API key credentials.

Request/response format

  • Content-Type: application/json for request bodies (except file uploads which use multipart/form-data)
  • Pagination: ?limit=50&offset=0 query parameters where supported
  • Correlation: X-Correlation-ID header for request tracing (auto-generated if not provided)

HTTP methods

GET POST PUT DELETE PATCH

1. Authentication

Account management, login, tokens, and API key operations. See API Authentication for detailed auth flow documentation.

Method Path Description Auth
POST /auth/register Create a new account (requires CAPTCHA) None
POST /auth/login Authenticate and receive JWT + refresh cookie None
POST /auth/logout Revoke refresh token and clear cookie User
POST /auth/refresh Rotate refresh token and get new JWT Cookie
GET /auth/me Get current user profile User
PUT /auth/profile Update display name and profile info User
PATCH /auth/settings Update user preferences (theme, language) User
POST /auth/password Change password (revokes all sessions) User
POST /auth/verify-email Verify email with token from email link None
POST /auth/resend-verification Resend verification email (3/hour limit) None
POST /auth/forgot-password Request password reset email (requires CAPTCHA) None
POST /auth/reset-password Set new password with reset token None
GET /auth/api-keys List your API keys User
POST /auth/api-keys Create a new API key (Pro/Enterprise) User
DELETE /auth/api-keys/{key_id} Revoke an API key User
POST /auth/account/delete Request account deletion (30-day grace period) User

2. Chat & Conversations

Send messages and retrieve conversation history. The async streaming flow is the primary way to interact with Thallus programmatically.

POST /chat/stream
→
task_id
→
GET /progress (SSE)
→
GET /result
Method Path Description Auth
POST /chat/stream Start async chat task, returns task_id immediately User
GET /chat/{task_id}/progress SSE stream of progress events User
GET /chat/{task_id}/progress/state Get all events as JSON (for recovery) User
GET /chat/{task_id}/result Get final response after completion User
GET /chat/active Check for active/completed tasks (page refresh recovery) User
POST /chat Synchronous chat (waits for full response) User
GET /conversations List conversations (paginated) User
GET /conversations/{conversation_id}/messages Get message history for a conversation User

Chat request body:

{
  "message": "Your question here",
  "conversation_id": "optional-uuid",
  "mode": "auto"
}

Mode options: auto, ask, research, investigate. See Chat Modes for when to use each mode.

For full streaming details, see Streaming & SSE.

3. Documents

Upload, manage, search, and organize documents. Files are processed asynchronously — after uploading, check the processing status before querying.

Method Path Description Auth
POST /documents/upload Upload a document (multipart/form-data, max 50 MB) User
GET /documents List your documents (paginated) User
GET /documents/{document_id} Get document metadata User
DELETE /documents/{document_id} Delete a document User
GET /documents/{document_id}/status Check processing status User
GET /documents/{document_id}/download Download the original file User
GET /documents/{document_id}/chunks Get document chunks (paginated) User
PUT /documents/{document_id}/move Move document to a collection User
POST /documents/query Search documents by text or semantic similarity User

Collections:

Method Path Description Auth
GET /documents/collections List your collections User
POST /documents/collections Create a collection User
GET /documents/collections/{collection_id} Get collection details User
PUT /documents/collections/{collection_id} Update a collection User
DELETE /documents/collections/{collection_id} Delete a collection User

Admin document operations:

Method Path Description Auth
GET /documents/admin/collections List organization collections Admin
POST /documents/admin/collections Create an organization collection Admin
DELETE /documents/admin/collections/{collection_id} Delete an organization collection Admin
POST /documents/admin/upload Upload a document for the organization Admin

Document processing status values: pending, processing, completed, failed. Supported file types: PDF, DOCX, TXT, CSV, XLSX. See Document Management for more details.

4. Data Connections

Connect to external databases, discover schemas, manage relationships, and execute queries.

Connection management:

Method Path Description Auth
GET /data/connections List your database connections User
POST /data/connections Create a new connection User
GET /data/connections/{connection_id} Get connection details User
PUT /data/connections/{connection_id} Update connection settings User
DELETE /data/connections/{connection_id} Delete a connection User
POST /data/connections/test Test credentials before saving User
POST /data/connections/{connection_id}/test Test an existing connection User
POST /data/connections/{connection_id}/discover Discover schema from database User
POST /data/connections/{connection_id}/refresh-schema Refresh cached schema User

Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server, MongoDB, Snowflake, BigQuery, and more. See Connecting a Database for setup guides.

Tables and schema:

Method Path Description Auth
GET /data/connections/{connection_id}/tables List tables in a connection User
GET /data/connections/{connection_id}/schema Get full schema metadata User
GET /data/tables/{table_id} Get table details User
PUT /data/tables/{table_id} Update table metadata User
PATCH /data/connections/{connection_id}/table-metadata/{table_name} Update column descriptions User

Uploaded tables (CSV/XLSX):

Method Path Description Auth
POST /data/upload-table Upload CSV/XLSX as a queryable table User
GET /data/uploaded-tables List uploaded tables User
GET /data/uploaded-tables/{table_id} Get uploaded table details User
PATCH /data/uploaded-tables/{table_id} Update uploaded table User
DELETE /data/uploaded-tables/{table_id} Delete uploaded table User
GET /data/uploaded-tables/{table_id}/download Download uploaded table User

Relationships:

Method Path Description Auth
GET /data/relationships List all relationships in organization User
POST /data/relationships Create a relationship between tables User
PUT /data/relationships/{relationship_id} Update a relationship User
DELETE /data/relationships/{relationship_id} Delete a relationship User
POST /data/relationships/{relationship_id}/confirm Confirm an inferred relationship User
POST /data/relationships/infer Auto-infer relationships from column names User

Query execution:

Method Path Description Auth
POST /data/query Execute a query against a connection User

Data queries are rate-limited: 30/min per user, 100/min per organization, 3 concurrent per connection. See Rate Limiting.

PII and sensitivity (admin):

Method Path Description Auth
GET /admin/data/orgs/{org_id}/table-sensitivity Get table sensitivity settings Admin
GET /admin/data/orgs/{org_id}/columns/{table_name}/sensitivity Get column sensitivity levels Admin
PUT /admin/data/orgs/{org_id}/tables/{table_name}/sensitivity Set table sensitivity level Admin
POST /data/connections/{conn_id}/tables/{table}/columns/{col}/pii Mark column as PII User
DELETE /data/connections/{conn_id}/tables/{table}/columns/{col}/pii Unmark column as PII User

5. Workflows

Create, manage, and execute DAG-based workflows. See Workflow Overview for concepts.

Workflow CRUD:

Method Path Description Auth
GET /workflows List organization workflows User
POST /workflows Create a new workflow User
GET /workflows/{workflow_id} Get workflow details User
PUT /workflows/{workflow_id} Update workflow DAG User
DELETE /workflows/{workflow_id} Delete a workflow User

Lifecycle:

Method Path Description Auth
POST /workflows/{workflow_id}/activate Activate workflow (enable scheduling) User
POST /workflows/{workflow_id}/pause Pause a running workflow User
POST /workflows/{workflow_id}/run Execute workflow manually User

Generation:

Method Path Description Auth
POST /workflows/generate Generate workflow from natural language User

Nodes:

Method Path Description Auth
PATCH /workflows/{workflow_id}/nodes/{node_id} Update a workflow node User
POST /workflows/{workflow_id}/nodes/{node_id}/suggest-agents Get AI agent suggestions for a node User

Executions:

Method Path Description Auth
GET /workflows/{workflow_id}/executions/{execution_id} Get execution details User
GET /workflows/{workflow_id}/executions/{execution_id}/timeline Get execution timeline User

Versioning:

Method Path Description Auth
GET /workflows/{workflow_id}/versions List workflow versions User
GET /workflows/{workflow_id}/versions/{version_id} Get version details User
POST /workflows/{workflow_id}/versions/{version_id}/restore Restore to a previous version User
GET /workflows/{workflow_id}/versions/compare Compare two versions User

Approvals:

Method Path Description Auth
GET /workflows/approvals/pending List pending approvals User
GET /workflows/approvals/{approval_id} Get approval details User
POST /workflows/approvals/{approval_id}/approve Approve a pending step User
POST /workflows/approvals/{approval_id}/reject Reject a pending step User

Usage:

Method Path Description Auth
GET /workflows/usage Get execution rate limit status User

6. Agents

Hierarchical agent access control across four tiers: Platform → Organization → Group → User. The most specific setting wins.

Platform level (system-wide defaults):

Method Path Description Auth
GET /admin/agents/platform/agents List all platform agents with settings Superadmin
PUT /admin/agents/platform/agents/{agent_name} Update platform agent settings Superadmin

Organization level:

Method Path Description Auth
GET /admin/agents/orgs/{org_id}/agents List agents for organization Admin
PUT /admin/agents/orgs/{org_id}/agents/{agent_name} Update org-level agent settings Admin

Group level:

Method Path Description Auth
GET /admin/agents/orgs/{org_id}/groups/{group_id}/agents List agents for group Admin
PUT /admin/agents/orgs/{org_id}/groups/{group_id}/agents/{agent_name} Set group agent permissions Admin

User level:

Method Path Description Auth
GET /admin/agents/users/{user_id}/agents Get agents accessible to user Admin
PUT /admin/agents/users/{user_id}/agents/{agent_name} Set user-level agent permissions Admin
GET /admin/agents/user-overrides/search Search user agent overrides Admin
GET /admin/agents/user-overrides/list List all user overrides Admin

User-facing agent endpoints:

Method Path Description Auth
GET /agents List available agents for current user User
GET /agents/{agent_name}/tools List tools for an agent User
GET /agents/{agent_name}/settings Get agent settings User
PUT /agents/{agent_name}/settings Update agent settings User

See Agent Access Control for the full access control model.

7. Settings

User-level model configuration for BYOK (Bring Your Own Key) users.

Method Path Description Auth
GET /settings/models Get current model configuration User
PUT /settings/models Save BYOK provider and model config User
POST /settings/models/validate Validate API keys by testing a completion User
DELETE /settings/models Remove BYOK config (revert to platform defaults) User
GET /settings/models/providers List supported LLM/embedding providers User

See Model Configuration for BYOK setup.

8. Billing

Plan management, checkout, and team operations. Most endpoints require billing admin permissions.

Method Path Description Auth
GET /billing/plans List available plans and pricing User
GET /billing/status Get current billing status User
POST /billing/checkout Create a Stripe checkout session Admin
POST /billing/portal Open the Stripe customer portal Admin
POST /billing/activate Activate subscription after checkout User
POST /billing/overage-cap Set monthly overage spending limit Admin
POST /billing/invite Invite a team member to the organization Admin
GET /billing/team List organization team members Admin
DELETE /billing/team/{user_id} Remove a team member Admin

See Billing & Plans for plan details.

9. Integrations

Connect and manage external service providers (Google, Slack, Jira, GitHub, Linear, etc.).

Provider management:

Method Path Description Auth
GET /providers/available List available integration providers User
GET /providers/connected List your connected providers User
GET /providers/connected/{service} List connections for a specific service User
POST /providers/connect/credentials Connect with API key or credentials User
POST /providers/connect/oauth/start Start OAuth flow (redirects to provider) User
POST /providers/connect/oauth/callback OAuth callback handler None
POST /providers/disconnect Disconnect a provider User
POST /providers/refresh/{provider_name} Refresh provider connection User

Chat integration settings:

Method Path Description Auth
GET /integrations/chat-settings/{service_name} Get chat integration settings User
PUT /integrations/chat-settings/{service_name} Update chat service settings User
GET /integrations/user-mappings List user account mappings User
DELETE /integrations/user-mappings/{mapping_id} Delete a user mapping User

See Integrations Overview for provider setup guides.

10. Audit

Query audit logs, view statistics, and export activity data. Admin endpoints show organization-wide activity; self-service endpoints show only your own.

Admin audit endpoints:

Method Path Description Auth
GET /audit/logs Query audit logs (paginated, filterable) Admin
GET /audit/logs/{log_id} Get a specific log entry Admin
GET /audit/logs/correlation/{correlation_id} Get logs by correlation ID Admin
GET /audit/stats Audit statistics (by action, outcome) Admin
GET /audit/stats/users Per-user activity statistics Admin
GET /audit/retention/stats Retention policy statistics Superadmin
POST /audit/retention/cleanup Trigger audit log cleanup Superadmin
DELETE /audit/logs/user/{user_id} Delete a user's audit logs Superadmin

Self-service activity endpoints:

Method Path Description Auth
GET /audit/my-logs Your activity logs User
GET /audit/my-logs/stats Your activity statistics User
GET /audit/my-logs/conversations Your conversation activity User
GET /audit/my-logs/export Export your logs (CSV) User
GET /audit/my-logs/categories Available log categories User
GET /audit/actions List available audit actions User
GET /audit/outcomes List possible audit outcomes User

See Audit Logs for the audit system overview.

11. Memory

Manage persistent user memories that Thallus uses to personalize responses.

Method Path Description Auth
GET /memories List your memories (paginated) User
GET /memories/stats Get memory statistics User
GET /memories/{memory_id} Get a specific memory User
POST /memories Create a manual memory User
PUT /memories/{memory_id} Update memory content or importance User
DELETE /memories/{memory_id} Delete a memory User

Memory categories: MEMORIES, PREFERENCES, FACTS, PATTERNS. See Memory System for how memories are used.

Example request

EXAMPLE: START A CHAT TASK
POST /api/v1/chat/stream Authorization: Bearer eyJhbGci... Content-Type: application/json { "message": "Show me Q4 revenue by region", "mode": "research" }
RESPONSE (201)
{ "task_id": "550e8400-e29b-...", "status": "processing" }

After receiving the task_id, open an SSE connection to receive progress events. See Streaming & SSE for the complete flow.