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.

Review AI-assisted output

AgentQ responses and recommendations can vary by provider, model, and available context. Review generated interpretations and proposed changes before relying on them. Workflows that can change business-critical or regulated data should include an approval step and use the minimum required permissions.

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?"}
    ]
  }'

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

The response includes the header X-Chat-Session-Id: 42. The stream body uses data: messages:

data: {"type":"text-delta","delta":"I found 12 tables in sales_db..."}
data: [DONE]

Request body (Vercel AI format):

Parameter	Type	Required	Description
`messages`	array	Yes	Message content for this request. When continuing a saved session, AgentQ loads its prior conversation context.
`session_id`	integer	No	Existing session ID to continue a conversation. Send it as a top-level body field or as the `session_id` query parameter. If omitted, a new session is created.

Stream items:

Stream Item	Description
`text-delta`	Incremental text chunk from AgentQ.
`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]`	Sentinel indicating that the response stream is complete. Messages are persisted to the session.

The X-Chat-Session-Id response header identifies the created or continued 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": "Analyze Trends",
    "arguments": {
      "datastore_name": "analytics_warehouse",
      "timeframe": "month"
    }
  }'

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` returns both active and archived. `only` returns 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 returns an AgentResponse with step-by-step guidance. The result is AI-assisted output and should be reviewed in the business context where it will be used.

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 from a natural-language business rule or validation expectation. Confirm the expectation, target asset, and generated check behavior before using this endpoint in an automated workflow.

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 an AI-assisted interpretation of a specific data quality anomaly, including possible contributing factors, potential business impact, and suggested investigation or remediation steps. Treat these fields as suggestions to validate, not confirmed findings.

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 AI provider is configured. The stored routing value can represent a selected external model or the Qualytics-managed provider.

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": "qualytics:custom"
}

Get Supported Models

Discover the AI providers available to the deployment and their configuration metadata. Some providers expose a model list, while managed providers can omit model selection.

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": "qualytics",
      "name": "Qualytics",
      "example_models": [],
      "accepts_any_model": false,
      "no_model_selection": true,
      "requires_base_url": false
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "example_models": ["gpt-4o", "gpt-4-turbo", "o1", "o3-mini"],
      "accepts_any_model": true,
      "no_model_selection": false,
      "requires_base_url": false
    }
  ]
}

Get LLM Configuration

Retrieve the current AI provider configuration. Stored credentials are 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):

{
  "id": 42,
  "model_name": "anthropic:claude-sonnet-4-20250514",
  "base_url": null,
  "provider_config": null,
  "tenant_description": "Data stewardship team responsible for customer and order data"
}

Create LLM Configuration

Create the deployment-wide AI provider configuration. Credential and connection validation applies when the selected external provider requires it. The Qualytics-managed provider does not require a separate model, API key, or Base URL.

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": "qualytics",
    "tenant_description": "Data stewardship team responsible for customer and order data"
  }'

Response (201 Created):

{
  "id": 42,
  "model_name": "qualytics:custom",
  "base_url": null,
  "provider_config": null,
  "tenant_description": "Data stewardship team responsible for customer and order data"
}

Request body:

Parameter	Type	Required	Description
`model_name`	string	Yes	Provider selection from the supported-models endpoint. Use the bare provider ID `qualytics` for the Qualytics-managed provider, which has no model choice. External providers use a `provider:model` value.
`tenant_description`	string	Yes	Business context that helps AgentQ tailor responses and suggestions to your organization. Do not include secrets.
`api_key`	string	Conditional	Credential for providers that require an API key. Omit it for the Qualytics-managed provider and supported credential-free authentication methods. Stored credentials are encrypted.
`base_url`	string	No	Custom endpoint for compatible external providers such as Ollama, OpenRouter, or LiteLLM.
`provider_config`	object	Conditional	Additional fields required by the selected provider or authentication method.

Update LLM Configuration

Update any combination of fields. When editing an external provider that uses an API key, omit api_key to keep the stored key. Switching providers requires the fields needed by the new provider.

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 '{"tenant_description": "Data governance team responsible for finance reporting data"}'

Response (200 OK):

{
  "id": 42,
  "model_name": "qualytics:custom",
  "base_url": null,
  "provider_config": null,
  "tenant_description": "Data governance team responsible for finance reporting data"
}

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, including 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.