# AgentQ API

Source: https://userguide.qualytics.io/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](https://userguide.qualytics.io/using-the-platform/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.

> **Warning: 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.

> **Tip: Complete API Reference**
>
> For the full interactive API documentation with all request/response schemas, visit the [API docs](https://userguide.qualytics.io/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) 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:

```text
Authorization: Bearer YOUR_QUALYTICS_API_TOKEN
```

For instructions on generating a token, see [Tokens](https://userguide.qualytics.io/settings/access-tokens/getting-started/).

---

## 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: Example request and response**
>
> **Request**:
>
> ```bash
> 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:
>
> ```text
> 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 |
| Streaming inactivity watchdog | 1,800 seconds (30 minutes) |

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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> 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):
>
> ```json
> {
>   "success": true,
>   "message": "Prompt executed successfully",
>   "data": {"result": "## Quality Trends for analytics_warehouse\n..."},
>   "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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/agent/suggestions" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "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: Example request and response**
>
> **Request**:
>
> ```bash
> 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):
>
> ```json
> {
>   "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: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/chat-sessions?page=1&size=20" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "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: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/chat-sessions/generating" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> [123, 456]
> ```

---

### Get a Session

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

**Permission**: Member or above

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/chat-sessions/42" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK, abbreviated):
>
> ```json
> {
>   "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: Example request and response**
>
> **Request**:
>
> ```bash
> 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):
>
> ```json
> {
>   "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: Example request and response**
>
> **Request**:
>
> ```bash
> 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):
>
> ```json
> {"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: Example request and response**
>
> **Request**:
>
> ```bash
> 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: Example request and response**
>
> **Request**:
>
> ```bash
> 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: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X PATCH "https://your-instance.qualytics.io/api/chat-sessions/42/restore" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {"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` whose `data.result` holds AgentQ's answer as Markdown text. IDs of assets it creates may appear in that text, but are not guaranteed. 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: Example request and response**
>
> **Request**:
>
> ```bash
> 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):
>
> ```json
> {
>   "success": true,
>   "message": "Prompt executed successfully",
>   "data": {"result": "Created computed table **daily_revenue_by_region** (ID 87) in sales_db..."},
>   "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. |

**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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> 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):
>
> ```json
> {
>   "success": true,
>   "message": "Prompt executed successfully",
>   "data": {"result": "Created 2 quality checks on customers.email (IDs 101 and 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. |

**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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/agent/investigate-anomaly?anomaly_identifier=12345" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "success": true,
>   "message": "Prompt executed successfully",
>   "data": {"result": "## Investigation of anomaly 12345\n**Root cause:** ...\n**Impact:** ...\n**Remediation:** ..."},
>   "error": null
> }
> ```

**Query parameters**:

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

**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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> 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):
>
> ```json
> {
>   "success": true,
>   "message": "Prompt executed successfully",
>   "data": {"result": "## Quality Trends (last month)\nThe quality score dropped 3.2 points..."},
>   "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`). |

**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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/agent/llm-config/status" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/agent/supported-models" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK, abbreviated):
>
> ```json
> {
>   "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.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/agent/llm-config" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> 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"
>     }
>   }'
> ```
>
> **Response** (200 OK): the created integration, including its `id`, `type`, `connected`, `api_url`, and a `parameters` object. For the Qualytics-managed provider the stored `model_name` comes back as `qualytics:custom`, since that provider has no model to select.

**Request body**:

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | Always `"llm"` for the AI provider configuration. |
| `api_url` | string | No | Custom endpoint, for providers that need one such as Ollama or LiteLLM. Must be omitted for the Qualytics-managed provider. |
| `api_access_token` | string | Conditional | Credential for providers that require an API key. Omit it for the Qualytics-managed provider and for credential-free authentication methods. Stored credentials are encrypted. |
| `parameters.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. |
| `parameters.tenant_description` | string | Yes | Business context that helps AgentQ tailor responses and suggestions to your organization, 1 to 2000 characters. Do not include secrets. |
| `parameters.provider_config` | object | Conditional | Additional fields required by the selected provider or authentication method, such as an AWS region for Amazon Bedrock. |

> **Warning: A custom endpoint is rejected with the Qualytics provider**
>
> Sending `api_url` together with the Qualytics-managed provider fails with `HTTP 400 Bad Request` and nothing is saved. That provider reaches its own gateway using the deployment's identity, so there is no endpoint for you to set. Omit the field.

**Other responses**:

| Response | Cause |
| --- | --- |
| `HTTP 409 Conflict` | A configuration already exists. Change it with `PUT` instead of creating a second one. |
| `HTTP 400 Bad Request` | A field the selected provider requires is missing or invalid, such as the AWS region for Amazon Bedrock or the account identifier for Snowflake Cortex. |
| `HTTP 422 Unprocessable Content` | `model_name` or `tenant_description` is missing, the description is longer than 2000 characters, the provider prefix is not recognized, an API key is missing for a provider that requires one, the provider rejected the credential or could not be reached, or the Qualytics-managed provider was selected on a deployment that has no Qualytics-issued identifier. |
| `HTTP 403 Forbidden` | The caller is a Member. Creating, changing, and removing the configuration require Manager or above. |

---

### 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`.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> 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"
>     }
>   }'
> ```
>
> **Response** (200 OK): the updated integration.

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

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X DELETE "https://your-instance.qualytics.io/api/integrations/42" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (204 No Content)

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](https://userguide.qualytics.io/agentq/deep-dive/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.

*Last updated: November 5, 2026.*