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.

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

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: {"type":"text-delta","delta":"I found 12 tables in sales_db..."}
data: [DONE]

Request body (Vercel AI format):

Stream items:

The X-Chat-Session-Id response header identifies the created or continued session.

Timeouts:

This endpoint returns a stream immediately, so it is not bounded by an overall execution timeout. A turn that is still streaming text or calling tools continues to run; the inactivity watchdog only ends a stream that has produced no output or tool activity for the full idle window. The non-streaming endpoints below are bounded by a 300-second execution timeout and a 360-second route timeout.

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

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

{
  "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

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

{
  "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

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

{
  "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

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

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

Query parameters:

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

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

[123, 456]

Get a Session

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

Permission: Member or above

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

{
  "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

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

{
  "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)

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

{"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)

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

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)

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

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)

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

{"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

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"

{
  "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:

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

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"

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

Query parameters:

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

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

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

Query parameters:

Analyze Trends

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

Endpoint: POST /api/agent/analyze-trends

Permission: Member or above

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"

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

Query parameters:

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

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

{
  "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. The qualytics entry is absent on deployments that have no Qualytics-issued identifier. Providers come back sorted alphabetically by provider ID; the app is what pins Qualytics to the top of its selector.

supports_binary_content tells you whether the provider accepts file attachments at all. supported_attachment_media_types narrows that to the formats a provider can actually read when it handles only some of them; an empty list means no format restriction beyond supports_binary_content. The app uses both to decide whether to show the Attach button and which formats its file picker offers.

Endpoint: GET /api/agent/supported-models

Permission: Member or above

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

{
  "providers": [
    {
      "id": "openai",
      "name": "OpenAI",
      "example_models": ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
      "accepts_any_model": true,
      "no_model_selection": false,
      "requires_base_url": false,
      "supports_binary_content": true,
      "supported_attachment_media_types": [],
      "extra_fields": []
    },
    {
      "id": "qualytics",
      "name": "Qualytics",
      "example_models": [],
      "accepts_any_model": false,
      "no_model_selection": true,
      "requires_base_url": false,
      "supports_binary_content": true,
      "supported_attachment_media_types": [
        "application/json",
        "application/pdf",
        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "application/xml",
        "text/csv",
        "text/markdown",
        "text/plain",
        "text/tab-separated-values",
        "text/x-markdown",
        "text/xml"
      ],
      "extra_fields": []
    }
  ]
}

Get LLM Configuration

Retrieve the current AI provider configuration. Stored credentials are never returned.

Endpoint: GET /api/agent/llm-config

Permission: Member or above

When no provider is configured, this returns HTTP 404 Not Found rather than an empty object.

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

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

Create LLM Configuration

The AI provider configuration is stored as an integration, so it is created, changed, and removed through the integrations endpoints. Reading it stays on the AgentQ endpoints above: the configuration and its status under /api/agent/llm-config, and the provider list under /api/agent/supported-models.

Credential and connection validation applies when the selected external provider requires it. The Qualytics-managed provider needs no API key and no Base URL.

Endpoint: POST /api/integrations

Permission: Manager or above

curl -X POST "https://your-instance.qualytics.io/api/integrations" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "llm",
    "parameters": {
      "model_name": "qualytics",
      "tenant_description": "Data stewardship team responsible for customer and order data"
    }
  }'

Request body:

Other responses:

Update LLM Configuration

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

Endpoint: PUT /api/integrations/{id}

Permission: Manager or above

Use the id returned when the configuration was created, or the id from GET /api/agent/llm-config.

curl -X PUT "https://your-instance.qualytics.io/api/integrations/42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "model_name": "qualytics",
      "tenant_description": "Data governance team responsible for finance reporting data"
    }
  }'

An unknown id returns HTTP 404 Not Found. Pointing an existing configuration at a different host returns HTTP 400 Bad Request unless you also re-supply the credential, since the stored key belongs to the previous host.

Sending api_url together with the Qualytics-managed provider is rejected here the same way it is on create. Switching an existing configuration over to that provider clears any endpoint you had stored, rather than rejecting the change.

Delete LLM Configuration

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

Endpoint: DELETE /api/integrations/{id}

Permission: Manager or above

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

An unknown id returns HTTP 404 Not Found.

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.