You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Runs auto-migrations (ensure_* functions) for all database tables
Generates agent Python modules from database
Starts the webhook renewal background task (every 6 hours)
Mounts the Google ADK FastAPI sub-application
API Reference
Health
Method
Endpoint
Auth
Description
GET
/health
No
Health check
Authentication
Method
Endpoint
Auth
Description
POST
/api/auth/token
No
Login (email + password)
POST
/api/auth/refresh-token
No
Refresh JWT token
POST
/api/auth/logout
Yes
Clear refresh token cookie
POST
/api/auth/mfa/setup
Yes
Generate TOTP secret + QR code
POST
/api/auth/mfa/enable
Yes
Activate MFA
POST
/api/auth/mfa/verify
No
Complete login with MFA code
POST
/api/auth/mfa/disable
Yes
Turn off MFA
GET
/api/auth/mfa/status
Yes
Check MFA status
GET
/api/auth/mfa/backup-codes
Yes
Retrieve backup codes
Users
Method
Endpoint
Auth
Description
POST
/api/users
No
Create user account
GET
/api/users
Admin
List all users
GET
/api/users/me
Yes
Get current user profile
GET
/api/users/{user_id}
Yes
Get user by ID
PATCH
/api/users/{user_id}
Yes
Update user profile
DELETE
/api/users/{user_id}
Yes
Delete user
POST
/api/users/oauth/{provider}/callback
No
OAuth login (github, google, microsoft, linkedin)
Agents
Method
Endpoint
Auth
Description
GET
/api/agents
Yes
List user's agents
POST
/api/agents
Yes
Create agent
GET
/api/agents/{agent_id}
Yes
Get agent details
PUT
/api/agents/{agent_id}
Yes
Update agent
DELETE
/api/agents/{agent_id}
Yes
Delete agent
POST
/api/agents/{agent_id}/run
Yes
Start agent run (background)
GET
/api/agents/{agent_id}/status
Yes
Get run status
Create an agent:
POST /api/agents
{
"agent_name": "My Assistant",
"agent_model": "anthropic/claude-sonnet-4-5-20250929",
"agent_description": "Specialized agent for data analysis",
"agent_instruction": "You are an expert data analyst.",
"agent_type": "llm",
"agent_tools": ["tool_config_id_1", "tool_config_id_2"],
"sub_agents": [],
"memory_enabled": false,
"artifacts_enabled": false,
"tags": ["analytics"]
}
Agent types:
Type
Description
llm / base
Simple agent, direct execution
parallel
Sub-agents executed in parallel
sequential
Sub-agents executed in sequence
loop
Iterative execution
Sessions & Runs (ADK)
Method
Endpoint
Auth
Description
POST
/api/adk/sessions
Yes
Create conversation session
GET
/api/adk/sessions/list
Yes
List all sessions
GET
/api/adk/sessions/{agent}/{user}/{session}
Yes
Get conversation history
GET
/api/adk/sessions/{agent}/{user}/{session}/trace
Yes
Get agent execution trace
PATCH
/api/adk/sessions/{agent}/{user}/{session}
Yes
Update session state
DELETE
/api/adk/sessions/{agent}/{user}/{session}
Yes
Delete session
POST
/api/adk/run
Yes
Run agent (blocking)
POST
/api/adk/run_sse
Yes
Run agent (SSE streaming)
POST
/api/adk/schedule_run
Yes
Schedule recurring run
POST
/api/adk/run_now
Yes
Trigger immediate run
Run an agent:
POST /api/adk/run
{
"agent_name": "My Assistant",
"user_id": "user@example.com",
"session_id": "session_001",
"new_message": {
"role": "user",
"parts": [{ "text": "What is the forecast for next month?" }]
},
"run_mode": "single",
"streaming": false
}
Tools
Method
Endpoint
Auth
Description
GET
/api/tools
Yes
List all available tools
GET
/api/tools/{tool_name}/params
Yes
Get tool config parameters
GET
/api/tools_config
Yes
List user's tool configs
GET
/api/tools_config/{id}
Yes
Get tool config details
POST
/api/tools_config
Yes
Create tool config
DELETE
/api/tools_config/{id}
Yes
Delete tool config
GET
/api/mcp_configs
Yes
List MCP server configs
RAG
Method
Endpoint
Auth
Description
POST
/api/rag/index-files
Yes
Upload and index files
POST
/api/rag/index-url
Yes
Index a web URL
POST
/api/rag/index-db
Yes
Index database results (SQL query)
POST
/api/rag/index-db-nl
Yes
Index database results (natural language)
POST
/api/rag/index-s3
Yes
Index files from S3
GET
/api/rag/status/{knowledge_id}
Yes
Check indexing status
GET
/api/rag/knowledge/{agent_id}
Yes
List indexed sources
GET
/api/rag/stream/{agent_id}
Yes
Stream indexing progress (SSE)
POST
/api/rag/schema-cache/invalidate
Yes
Clear schema cache (text-to-SQL)
POST
/api/rag/webhook
No
RAG completion webhook (from th2llm)
Webhooks
Method
Endpoint
Auth
Description
POST
/api/webhooks/subscriptions
Yes
Create webhook subscription
GET
/api/webhooks/subscriptions
Yes
List subscriptions
PATCH
/api/webhooks/subscriptions/{id}
Yes
Update subscription
DELETE
/api/webhooks/subscriptions/{id}
Yes
Delete subscription
POST
/api/webhooks/subscriptions/{id}/renew
Yes
Manually renew subscription
POST
/api/webhooks/gmail/notifications
No
Gmail Pub/Sub push endpoint
POST
/api/webhooks/outlook/notifications
No
Outlook Graph push endpoint
GET
/api/webhooks/logs
Yes
List webhook execution logs
GET
/api/webhooks/logs/{log_id}
Yes
Get specific log
Integrations
Method
Endpoint
Auth
Description
GET
/api/integrations
Yes
List user's connected integrations
GET
/api/integrations/google/{service}/connect
Yes
Get Google OAuth URL (drive, gmail, calendar, sheets, docs)
POST
/api/integrations/google/callback
Yes
Google OAuth callback
GET
/api/integrations/microsoft/{service}/connect
Yes
Get Microsoft OAuth URL (outlook, teams, onedrive, sharepoint)
th2agent can automatically trigger agents when events occur in connected services (new email, etc.). Two providers are supported: Gmail (via Google Pub/Sub) and Outlook (via Microsoft Graph subscriptions).
How It Works
Email arrives → Provider pushes notification → th2agent receives it
→ Fetches new email content → Runs associated agent → Logs result
Webhook Subscription API
Method
Endpoint
Description
POST
/api/webhooks/subscriptions
Create subscription
GET
/api/webhooks/subscriptions
List subscriptions
PATCH
/api/webhooks/subscriptions/{id}
Update (agent, template, change_type)
DELETE
/api/webhooks/subscriptions/{id}
Delete and unsubscribe
POST
/api/webhooks/subscriptions/{id}/renew
Manually renew
GET
/api/webhooks/logs
View execution logs
Create a subscription:
POST /api/webhooks/subscriptions
{
"provider": "google_gmail",
"resource": "INBOX",
"agent_id": "AGENT_ID",
"change_type": "created",
"agent_message_template": "New email from {{ sender }}: {{ subject }}\n\n{{ body }}"
}
Automatic Renewal
Gmail watches expire after 7 days
Outlook subscriptions expire after 3 days
A background task runs every 6 hours and renews subscriptions expiring within 12 hours
Gmail Webhook Setup (Pub/Sub)
Architecture
Gmail ──push──▶ Google Pub/Sub ──HTTP POST──▶ th2agent
(topic) /api/webhooks/gmail/notifications
│
▼
Fetch new emails via Gmail API
│
▼
Run associated agent
Prerequisites
A Google Cloud project with billing enabled
Gmail API and Cloud Pub/Sub API enabled
A Google OAuth 2.0 application for workspace integration
Note: In the Google Cloud Console UI, the "Publisher" role may not appear in the dropdown by default — type "publisher" in the search bar to find it, or use the CLI command above.