Agent Q API

The Agent Q API provides programmatic access to Agent Q's chat capabilities, session management, specialized workflows, and LLM configuration. Use these endpoints to integrate Agent Q into your own applications, automate interactions, or build custom interfaces.

Complete API Reference

For the full interactive API documentation with all request/response schemas, visit the API docs.

All endpoints use the base URL of your Qualytics deployment (e.g., https://your-instance.qualytics.io/api).

Authentication

All Agent Q API endpoints require a Qualytics Personal API Token (PAT). Most endpoints require the Member role or higher; LLM configuration write endpoints require Manager.

Include the token in the Authorization header:

Authorization: Bearer YOUR_QUALYTICS_API_TOKEN

For instructions on generating a token, see Tokens.

Chat

Send a Message

Start or continue a conversation with Agent Q. Responses are streamed via Server-Sent Events (SSE) using the Vercel AI Data Stream Protocol.

Endpoint: POST /api/agent/chat

Permission: Member or above

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/agent/chat" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What tables are in our sales_db datastore?"}
    ],
    "data": {}
  }'

Response (200 OK, text/event-stream):

event: text-delta
data: {"delta": "I found 12 tables in sales_db..."}

event: tool-call
data: {"tool_name": "list_containers", "tool_call_id": "call_01"}

event: tool-output-available
data: {"tool_call_id": "call_01", "output": "[{\"name\": \"customers\", ...}]"}

event: done
data: {"session_id": 42}

Request body (Vercel AI format):

Parameter	Type	Required	Description
`messages`	array	Yes	Array of `{role, content}` objects representing the conversation history.
`data.session_id`	integer	No	Existing session ID to continue a conversation. If omitted, a new session is created automatically.

SSE events:

Event Type	Description
`text-delta`	Incremental text chunk from Agent Q.
`tool-call`	A tool invocation has started.
`tool-input-available`	Input parameters for a tool call are ready.
`tool-output-available`	A tool execution has completed and returned results.
`error`	An error occurred during processing.
`done`	The response stream is complete. Messages are persisted to the session.

Note

The chat endpoint is rate-limited to 10 requests per minute per user, with a maximum of 2 simultaneous streaming responses. Exceeding these limits returns HTTP 429 Too Many Requests.

Timeouts:

Layer	Timeout
Individual LLM API request	120 seconds
Overall agent execution	300 seconds
HTTP route handler	360 seconds

Execute a Prompt

Execute a named MCP prompt directly for single-turn interactions without session context.

Endpoint: POST /api/agent/prompt

Permission: Member or above

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/agent/prompt" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_name": "list_containers",
    "arguments": {"datastore_name": "analytics_warehouse"}
  }'

Response (200 OK):

{
  "success": true,
  "message": "...",
  "data": {},
  "error": null
}

Get Suggestions

Retrieve 3 LLM-generated contextual prompt suggestions based on your data assets and active anomalies. These are the same suggestions shown in the Agent Q empty state in the UI.

Endpoint: GET /api/agent/suggestions

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/agent/suggestions" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "suggestions": [
    "Investigate the recent spike in null values on the customers table",
    "Create a not-null check on the order_id field in transactions",
    "Show quality score trends for sales_db over the last 30 days"
  ]
}

Chat Sessions

Agent Q organizes conversations into persistent sessions. Each session stores its message history, activated tools, and a generated summary for context resumption.

Create a Session

Endpoint: POST /api/chat-sessions

Permission: Member or above

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/chat-sessions" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sales Data Investigation"}'

Response (200 OK):

{
  "id": 42,
  "title": "Sales Data Investigation",
  "archived": false,
  "created": "2026-04-24T14:30:00.000000Z"
}

List Sessions

Endpoint: GET /api/chat-sessions

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/chat-sessions?page=1&size=20" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "items": [
    {"id": 42, "title": "Sales Data Investigation", "archived": false}
  ],
  "total": 1,
  "page": 1,
  "size": 20
}

Query parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1).
`size`	integer	Sessions per page (default: 50).
`search`	string	Filter by session title.
`archived`	string	`include` — return both active and archived. `only` — return archived only.

Get Active Generating Sessions

Returns the IDs of sessions that are currently streaming a response. Useful for showing loading indicators when the user navigates away.

Endpoint: GET /api/chat-sessions/generating

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/chat-sessions/generating" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

[123, 456]

Get a Session

Endpoint: GET /api/chat-sessions/{session_id}

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/chat-sessions/42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK, abbreviated):

{
  "id": 42,
  "title": "Sales Data Investigation",
  "archived": false,
  "messages": [
    {"role": "user", "content": "What tables are in sales_db?"},
    {"role": "assistant", "content": "I found 12 tables..."}
  ]
}

Get Session Messages

Retrieve paginated messages for a session (default: 50 per page, newest first).

Endpoint: GET /api/chat-sessions/{session_id}/messages

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/chat-sessions/42/messages?page=1&size=50" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "items": [
    {"role": "assistant", "content": "I found 12 tables...", "created": "..."},
    {"role": "user", "content": "What tables are in sales_db?", "created": "..."}
  ],
  "total": 2,
  "page": 1,
  "size": 50
}

Update a Session

Rename or update session metadata.

Endpoint: PUT /api/chat-sessions/{session_id}

Permission: Member or above (session owner)

Example request and response

Request:

curl -X PUT "https://your-instance.qualytics.io/api/chat-sessions/42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title"}'

Response (200 OK):

{"id": 42, "title": "Updated Title", "archived": false}

Archive a Session

Soft-deletes a session. Archived sessions are read-only and can be restored.

Endpoint: DELETE /api/chat-sessions/{session_id}

Permission: Member or above (session owner)

Example request and response

Request:

curl -X DELETE "https://your-instance.qualytics.io/api/chat-sessions/42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (204 No Content)

Hard-Delete a Session

Permanently deletes a session. This cannot be undone.

Endpoint: DELETE /api/chat-sessions/{session_id}?archive=false

Permission: Member or above (session owner)

Example request and response

Request:

curl -X DELETE "https://your-instance.qualytics.io/api/chat-sessions/42?archive=false" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (204 No Content)

The archive query parameter defaults to true (soft-delete). Pass archive=false for a permanent hard delete.

Restore an Archived Session

Endpoint: PATCH /api/chat-sessions/{session_id}/restore

Permission: Member or above (session owner)

Example request and response

Request:

curl -X PATCH "https://your-instance.qualytics.io/api/chat-sessions/42/restore" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{"id": 42, "title": "Sales Data Investigation", "archived": false}

Specialized Workflow Endpoints

These endpoints execute guided multi-step AI workflows for specific data quality tasks. Each one calls the underlying workflow tool and returns an AgentResponse with step-by-step guidance.

Transform Dataset

Create computed tables, files, or cross-datastore joins through natural language. Agent Q determines the correct asset type from the description.

Endpoint: POST /api/agent/transform-dataset

Permission: Member or above

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/agent/transform-dataset?asset_name=daily_revenue_by_region&source_description=transactions%20table%20in%20sales_db&transformation_criteria=Aggregate%20daily%20revenue%20by%20region%2C%20include%20only%20completed%20orders" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "success": true,
  "message": "Created computed table daily_revenue_by_region in sales_db.",
  "data": {"asset_id": 87, "asset_type": "computed_table"},
  "error": null
}

Query parameters:

Parameter	Type	Required	Description
`asset_name`	string	Yes	Name for the new computed asset.
`source_description`	string	Yes	Description of the source data (datastore and container).
`transformation_criteria`	string	Yes	Natural-language description of the transformation logic.

Generate Quality Check

Create a data quality check by describing the business rule or validation expectation.

Endpoint: POST /api/agent/generate-quality-check

Permission: Member or above

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/agent/generate-quality-check?datastore_name=sales_db&container_name=customers&expectation=Ensure%20the%20email%20field%20is%20never%20null%20and%20matches%20a%20valid%20email%20format" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "success": true,
  "message": "Created 2 quality checks on customers.email.",
  "data": {"check_ids": [101, 102]},
  "error": null
}

Query parameters:

Parameter	Type	Required	Description
`datastore_name`	string	Yes	Target datastore.
`container_name`	string	Yes	Target container (table or file).
`expectation`	string	Yes	Natural-language description of the business rule or validation expectation.

Investigate Anomaly

Get AI-powered analysis of a specific data quality anomaly, including root cause context, business impact, and suggested remediation steps.

Endpoint: POST /api/agent/investigate-anomaly

Permission: Member or above

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/agent/investigate-anomaly?anomaly_identifier=12345" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "success": true,
  "message": "Investigation summary...",
  "data": {"root_cause": "...", "impact": "...", "remediation": ["..."]},
  "error": null
}

Query parameters:

Parameter	Type	Required	Description
`anomaly_identifier`	string	Yes	Numeric ID or UUID of the anomaly to investigate.

Analyze Trends

Analyze data quality trends, score patterns, and anomaly volume changes over time.

Endpoint: POST /api/agent/analyze-trends

Permission: Member or above

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/agent/analyze-trends?datastore_name=sales_db&container_name=transactions&timeframe=month" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "success": true,
  "message": "Trend analysis...",
  "data": {"timeframe": "month", "score_change": -3.2, "anomaly_volume": "..."},
  "error": null
}

Query parameters:

Parameter	Type	Required	Description
`datastore_name`	string	Yes	Target datastore.
`container_name`	string	No	Scope to a specific container.
`field_name`	string	No	Scope to a specific field.
`timeframe`	string	No	`week`, `month`, `quarter`, or `year` (default: `month`).

LLM Configuration

Get Configuration Status

Check whether an LLM provider is configured. Returns model name and web search enablement.

Endpoint: GET /api/agent/llm-config/status

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/agent/llm-config/status" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "is_configured": true,
  "model_name": "gpt-4o",
  "web_search_enabled": false
}

Get Supported Models

Discover all available LLM providers and their supported models. This endpoint is the authoritative source for provider/model combinations.

Endpoint: GET /api/agent/supported-models

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/agent/supported-models" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK, abbreviated):

{
  "providers": [
    {
      "id": "openai",
      "name": "OpenAI",
      "example_models": ["gpt-4o", "gpt-4-turbo", "o1", "o3-mini"],
      "accepts_any_model": true,
      "requires_base_url": false
    }
  ]
}

Get LLM Configuration

Retrieve the current LLM configuration. The API key is never returned.

Endpoint: GET /api/agent/llm-config

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/agent/llm-config" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "model_name": "anthropic:claude-sonnet-4-20250514",
  "base_url": null,
  "web_search_enabled": false
}

Create LLM Configuration

The API key is validated and the connection is tested before the configuration is stored.

Endpoint: POST /api/agent/llm-config

Permission: Manager or above

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/agent/llm-config" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "anthropic:claude-sonnet-4-20250514",
    "api_key": "YOUR_LLM_API_KEY"
  }'

Response (201 Created):

{
  "model_name": "anthropic:claude-sonnet-4-20250514",
  "base_url": null,
  "web_search_enabled": false
}

Request body:

Parameter	Type	Required	Description
`model_name`	string	Yes	Provider and model in `provider:model` format (e.g., `openai:gpt-4o`, `anthropic:claude-sonnet-4-20250514`).
`api_key`	string	Yes	Your API key for the LLM provider. Stored encrypted.
`base_url`	string	No	Custom endpoint URL for OpenAI-compatible providers (Ollama, OpenRouter, LiteLLM).

Update LLM Configuration

Update any combination of fields. Omit api_key to keep the current key.

Endpoint: PATCH /api/agent/llm-config

Permission: Manager or above

Example request and response

Request:

curl -X PATCH "https://your-instance.qualytics.io/api/agent/llm-config" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model_name": "openai:gpt-4o"}'

Response (200 OK):

{
  "model_name": "openai:gpt-4o",
  "base_url": null,
  "web_search_enabled": false
}

Delete LLM Configuration

Removes the configuration and disables Agent Q until a new provider is configured.

Endpoint: DELETE /api/agent/llm-config

Permission: Manager or above

Example request and response

Request:

curl -X DELETE "https://your-instance.qualytics.io/api/agent/llm-config" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (204 No Content)

Rate Limits

For the complete limits reference — rate limits, token budgets, timeouts, and SQL constraints — see Agent Q Limits.

Exceeding the per-minute or concurrent limits returns HTTP 429 Too Many Requests. Token and request limits return an error message indicating the cost control was reached.