AgentQ API

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

Where MCP is meant for interactive AI clients such as Claude Desktop, these endpoints put the same capabilities behind ordinary REST calls, so you can:

• Build custom applications that use natural language for data quality tasks.
• Add AI-assisted data quality steps to workflows you already run.
• Create internal tools and chatbots that reach your data infrastructure.
• Use the AI provider and Business Context already configured for your deployment.

Every endpoint runs against the same tools the chat uses, and the actions available through them still follow the authenticated user's own Qualytics permissions.

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) or a token issued to a designated service account. Most endpoints require the Member role or higher, and the AgentQ 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.

Use cases:

• Interactive exploration: build chatbots or conversational interfaces that let users explore data assets in their own words.
• Multi-step workflows: handle requests that need context and several decisions along the way.
• General assistance: answer questions about quality status, anomaly patterns, or check configuration.

Example prompts:

• "Show me the schema for the customer_orders table in our PostgreSQL datastore"
• "What anomalies were detected in the last 24 hours?"
• "Which quality checks are failing most frequently across all our datastores?"
• "Help me understand why the order_total check keeps failing"

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
}

Use cases:

• Registered workflows: invoke a supported named prompt from an application or script.
• Single-turn analysis: run a supported analysis without keeping conversation state.
• Report drafting: generate a summary for a responsible owner to review.

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:

Use cases:

• Automated data preparation: fold dataset creation into ETL pipelines or data workflows.
• Self-service analytics: let business users create derived datasets without writing SQL.
• Cross-system integration: build unified views across databases and data lakes programmatically.

Example descriptions:

• "Join the customers table from our Snowflake warehouse with the support_tickets table from PostgreSQL on customer_id, filtering to only active customers"
• "Create a computed file from our S3 landing zone that filters out test records and standardizes the date format"
• "Build a daily summary table that calculates average order value and order count by region"

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:

Use cases:

• Bulk check creation: establish quality checks across many datasets programmatically.
• Rule migration: turn business rules held in documentation into executable checks.
• Policy-to-check drafting: turn an approved policy requirement into candidate checks for subject matter review.
• Data contract implementation: create candidate checks from reviewed data contract specifications.

Example expectations:

• "The order_total in the orders table should always be positive and less than 1,000,000"
• "ship_date must be after order_date for all records in the shipments table"
• "The status field should only contain 'pending', 'processing', 'shipped', or 'delivered'"
• "customer_id in transactions must exist in the customers table"

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:

Use cases:

• Alert context: add an AI-generated interpretation to an alert for review.
• Incident report drafting: draft a readable explanation for an incident owner to verify.
• Triage support: suggest possible severity, contributing factors, and next steps.
• Stakeholder update drafting: prepare a plain-language summary for a responsible owner to review.

What the response covers:

• What quality rule was violated, in plain language.
• Context about the affected dataset and fields.
• The count and pattern of affected records.
• A suggested business impact.
• Suggested investigation or remediation steps, which still need validation.

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:

Use cases:

• Quality reporting: produce trend reports for stakeholders and management.
• Improvement tracking: measure what a quality initiative changed over time.
• Regression detection: find when a metric started sliding.

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

Integration Patterns

Review-Assisted Quality Check Setup

When onboarding a new data source, use the chat endpoint to ask for candidate checks based on the available schema information. Present the candidates to a qualified reviewer, then call POST /api/agent/generate-quality-check only for approved business expectations. The endpoint accepts datastore_name, container_name, and expectation as query parameters.

AI-Assisted Anomaly Alerts

Call POST /api/agent/investigate-anomaly with anomaly_identifier as a query parameter to add AI-generated context to an alert. Label the interpretation as AI-generated and route it to the responsible owner for validation before treating suggested causes, impact, or next steps as confirmed.

Self-Service Data Preparation

Build an internal tool that lets analysts request datasets in their own words. Call POST /api/agent/transform-dataset with asset_name, source_description, and transformation_criteria as query parameters. Review the requested sources and the transformation before the call, then validate the created asset before anything downstream uses it.

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.