AgentQ API

The AgentQ API provides programmatic access to AgentQ's chat capabilities, session management, specialized workflows, and LLM configuration. Use these endpoints to integrate AgentQ 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 AgentQ 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 AgentQ. 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 AgentQ.
`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 AgentQ 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

AgentQ 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. AgentQ 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 AgentQ 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 AgentQ 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.