> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Using the Agent Tasks API
export const designer = "Designer";
export const maia_agents = "Maia AI Agents";
The Agent Tasks API endpoints let you programmatically create, monitor, and manage {maia_agents}' tasks. You give {maia_agents} an instruction and they work asynchronously in the background.
The `ai/agents/tasks` endpoints allow you to perform the following actions:
* **[Create a task](#create-a-task):** Give {maia_agents} an instruction to work on. Returns the task ID you need for all subsequent actions.
* **[List tasks](#list-tasks):** Retrieve a list of all tasks, optionally filtered by any combination of the task's project, branch, and status.
- **[Find the status of a task](#find-the-status-of-a-task):** Check the current status and details of a task.
- **[Handle decisions](#handle-decisions):** Approve tool use or answer questions when {maia_agents} pause mid-task and ask for your input.
- **[Read messages](#read-messages):** Retrieve the message history for a task to follow {maia_agents}' reasoning or collect their output.
- **[Send a follow-up message](#send-a-follow-up-message):** Send additional instructions to an existing task—for example, to give clarification, redirect {maia_agents}, or resume them after they've stopped.
- **[Stop a task](#stop-a-task):** Stop a running task. {maia_agents} finish what they're currently doing before stopping.
- **[Delete a task](#delete-a-task):** Permanently delete a task and all of its associated data.
- **[Update task permissions](#update-task-permissions):** Replace the full set of tools {maia_agents} are permitted to use.
A *task* is the overall piece of work you give {maia_agents} to complete—comparable to opening a new chat with {maia_agents} in {designer} and sending your opening prompt. A *message* is an individual instruction sent within that task, comparable to continuing that same chat.
{maia_agents} work under the identity of the user associated with the API key. This means that any changes you make using the Agent Tasks API endpoints aren't automatically visible to other project users. To review or merge the work, ask {maia_agents} to commit and push changes to the target branch. You can either include this in your original instruction when you create the task, or send a follow-up message as part of the existing task. Each task works in isolation on its own branch, so creating a new task always starts a completely separate piece of work that isn't connected to any previous task.
These endpoints currently only work with Matillion-hosted and GitHub projects.
***
## Create a task
Use this endpoint to create a new task and send {maia_agents} an instruction to work on. A successful request returns a task ID that you use in all subsequent requests.
### Request fields
| Field | Required | Description |
| ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Top-level fields** | | |
| `message` | Yes | The instruction or question to send to the agent—your opening prompt. |
| `agentConfig` | Yes | Sets the project, environment, and behavior for the task—see `agentConfig` fields below. |
| `grantedPermissions` | No | Tools to pre-approve so the agent doesn't need to pause and ask for permission mid-task. |
| **agentConfig fields** | | |
| `name` | Yes | The agent type. Currently always `"data_engineer_agent"`. |
| `mode` | Yes | `"ACT"` = the agent makes changes. `"PLAN"` = the agent produces a plan only, no changes are made. |
| `projectId` | Yes | The ID of the project the agent will work in. |
| `sourceBranchName` | Yes | The branch the agent reads from. When creating a new branch, this is the branch to branch off from. |
| `environmentName` | Yes | The environment the agent will use when running pipelines. |
| `targetBranchName` | Conditional | The name of a new branch for the agent to create and write changes to. Required unless `generateBranch` is `true`. |
| `generateBranch` | Conditional | Set to `true` to let the agent auto-generate a branch name. Required unless `targetBranchName` is provided. Ignored if `targetBranchName` is also provided. |
| `graphId` | No | The ID of a Knowledge Layer service graph. |
| `workingDirectory` | No | A folder path within the project to scope the agent's work. |
| **grantedPermissions fields** | | |
| `toolName` | Yes | The name of a tool to pre-approve. For example, `"execute_sql"`. For a list of available tools and their `toolName` values, read [Available tools](#available-tools) below. |
### Example request
Base URL: `POST /v1/ai/agents/tasks`
Example request body:
```json theme={null}
{
"message": "Build a pipeline to load sales data from S3 into Snowflake, transforming the date columns to UTC.",
"agentConfig": {
"name": "data_engineer_agent",
"mode": "ACT",
"projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"sourceBranchName": "main",
"environmentName": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"targetBranchName": "feature/sales-pipeline"
},
"grantedPermissions": [
{ "toolName": "execute_sql" }
]
}
```
Example success response:
```
HTTP 201 Created
{
"taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"status": "RUNNING",
"agentName": "data_engineer_agent",
"createdAt": "2026-04-08T10:23:45+00:00"
}
```
***
## List tasks
Use this endpoint to retrieve a list of all tasks. You can filter results by any combination of the task's project, branch, and status.
### Query parameters
| Parameter | Description |
| ----------- | -------------------------------------------------------------------------------------------- |
| `projectId` | Return only tasks belonging to this project. |
| `branchId` | Return only tasks associated with this branch. |
| `status` | Return only tasks in a specific status. One of: `RUNNING`, `STOPPED`, `STOPPING`, `ERRORED`. |
| `page` | The zero-indexed page number to return. Default `0`. |
| `size` | Number of tasks to return per page. Default `20`, minimum `1`, maximum `100`. |
### Example request
Base URL: `GET /v1/ai/agents/tasks`
Example success response:
```
HTTP 200 OK
{
"tasks": [
{
"taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"status": "RUNNING",
"agentName": "data_engineer_agent",
"mode": "ACT",
"description": "Build a pipeline to load sales data from S3 into Snowflake",
"createdAt": "2026-05-05T10:30:00Z",
"modifiedAt": "2026-05-15T10:25:00+00:00",
"projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"branchId": "feature/sales-pipeline"
}
],
"page": 0,
"size": 20,
"total": 1
}
```
***
## Find the status of a task
Use this endpoint to check the current status and details of a task.
### Task statuses
| Status | Meaning |
| ---------- | ---------------------------------------------------------- |
| `RUNNING` | The agent is actively working. |
| `STOPPING` | A stop has been requested; the agent is wrapping up. |
| `STOPPED` | The agent has paused—see note below. |
| `ERRORED` | Something went wrong. Check the task messages for details. |
`STOPPED` means two different things depending on whether the task has pending decisions:
* `STOPPED` + empty `pendingDecisions` = the agent has finished. Treat as terminal.
* `STOPPED` + non-empty `pendingDecisions` = the agent is paused waiting for human input. This is not a terminal state—submit decisions to resume the task.
Checking only the `status` field may cause paused tasks to be incorrectly marked as completed.
### Example request
Base URL: `GET /v1/ai/agents/tasks/{taskId}`
Example success response:
```
HTTP 200 OK
{
"taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"status": "STOPPED",
"description": "Build a pipeline to load sales data from S3 into Snowflake",
"createdAt": "2026-04-08T10:23:45+00:00",
"modifiedAt": "2026-04-08T10:26:10+00:00",
"agentConfig": {
"name": "data_engineer_agent",
"mode": "ACT",
"projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"sourceBranchName": "main",
"environmentName": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"targetBranchName": "feature/sales-pipeline"
},
"grantedPermissions": [
{ "toolName": "execute_sql" }
],
"pendingDecisions": [
{
"type": "tool",
"toolName": "execute_sql",
"toolId": "e5f6a7b8-c9d0-1234-efab-345678901234",
"permissionMessage": {
"title": "Execute SQL query",
"body": "The agent wants to run: SELECT * FROM sales LIMIT 10"
},
"toolInput": {
"query": "SELECT * FROM sales LIMIT 10"
}
}
]
}
```
***
## Handle decisions
Use this endpoint to submit decisions on a stopped task and resume the agent. When `pendingDecisions` is not empty on a `STOPPED` task, the agent is paused waiting for your input.
There are two decision types:
* Approve the use of a tool so that {maia_agents} can use this tool to complete their task.
* Answer a question that {maia_agents} asked as part of completing their task.
### Example request: Tool approval
Base URL: `POST /v1/ai/agents/tasks/{taskId}/decisions`
```json theme={null}
{
"decisions": [
{
"type": "tool",
"id": "",
"approved": true,
"scope": "ONCE"
}
]
}
```
The `id` value comes from `pendingDecisions[].toolId` on the task. Set `scope` to `"CONVERSATION"` to pre-approve the tool for the remainder of the task—useful when the agent will call the same tool many times in a loop.
### Example request: Answer a question
```json theme={null}
{
"decisions": [
{
"type": "question",
"id": "",
"answers": [
{
"questionIndex": 0,
"selectedOptions": ["yes"]
}
]
}
]
}
```
Example success response:
```
HTTP 202 Accepted
{
"pendingDecisions": []
}
```
***
## Read messages
Use this endpoint to retrieve the message history for a task and follow the agent's reasoning or collect its output. This is the primary way to see what the agent is doing and read its results.
### Query parameters
| Parameter | Description |
| ----------------- | ----------------------------------------------------------------------------------- |
| `limit` | Maximum messages per page. Default 25, maximum 1000. |
| `paginationToken` | Pass the value from the previous response's `more` field to retrieve the next page. |
### Example request
Base URL: `GET /v1/ai/agents/tasks/{taskId}/messages`
The response includes a `results` array of events ordered chronologically, and a `more` field containing the pagination token for the next page. When `more` is absent and the task status is `STOPPED` or `ERRORED`, there are no more events to retrieve.
***
## Send a follow-up message
Use this endpoint to send an additional instruction to an existing task—for example, to give clarification, redirect the agent, or resume it after it has stopped.
### Request fields
| Field | Required | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Top-level fields** | | |
| `message` | Yes | The follow-up instruction or question to send to the agent. |
| `grantedPermissions` | No | Additional tools to grant. Added on top of any permissions already granted to the task. |
| `agentConfig` | No | Optional overrides to the agent's behavior from this message onward. Only `mode` and `targetBranchName` can be overridden—see `agentConfig` fields below. |
| **agentConfig fields** | | |
| `name` | Yes | Must be `"data_engineer_agent"`. |
| `mode` | No | Override the agent mode: `"ACT"` to make changes, `"PLAN"` to produce a plan only. |
| `targetBranchName` | No | Override the branch the agent writes changes to. |
### Example request
Base URL: `POST /v1/ai/agents/tasks/{taskId}/messages`
Example request body:
```json theme={null}
{
"message": "Also add a step to handle null values in the date columns before transforming.",
"agentConfig": {
"name": "data_engineer_agent",
"mode": "ACT"
}
}
```
Example success response:
```
HTTP 202 Accepted
{
"taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}
```
***
## Stop a task
Use this endpoint to stop a task that is running. {maia_agents} finish what they are currently doing before stopping.
Use `GET /v1/ai/agents/tasks/{taskId}` to monitor the task status until it reaches `STOPPED` before attempting further operations on the task. Once stopped, you can resume the task by sending it a new message, or delete it.
### Example request
Base URL: `POST /v1/ai/agents/tasks/{taskId}/stop`
No request body is required.
Example success response:
```
HTTP 204 No Content
```
***
## Delete a task
Use this endpoint to permanently delete a task and all of its associated data. Deleting a task means that you won't have an audit trail for any changes that {maia_agents} made as part of the deleted task.
You can't delete a task with a status of `RUNNING`—the request will fail with a `409 Conflict`. [Stop the task](#stop-a-task) first and wait for it to reach `STOPPED` before deleting.
### Example request
Base URL: `DELETE /v1/ai/agents/tasks/{taskId}`
Example success response:
```
HTTP 204 No Content
```
***
## Update task permissions
Use this endpoint to replace the full set of tools the agent has been granted permission to use. This is a complete replacement—whatever you send becomes the new list. For a list of available tools and their `toolName` values, read [Available tools](#available-tools) below.
This endpoint replaces the full permission set, not individual permissions. To add a single permission, re-send the complete list including the new entry. Pass an empty list (`[]`) to clear all permissions.
### Example request
Base URL: `PUT /v1/ai/agents/tasks/{taskId}/permissions`
Example request body:
```json theme={null}
{
"grantedPermissions": [
{ "toolName": "execute_sql" },
{ "toolName": "read_file" }
]
}
```
Example success response:
```
HTTP 200 OK
{
"taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"grantedPermissions": [
{ "toolName": "execute_sql" },
{ "toolName": "read_file" }
]
}
```
***
## Available tools
The following table lists all tools that {maia_agents} can use as part of a task. Use the names in the **Tool name** column as the value of the `toolName` field when [creating a task](#create-a-task) or [updating task permissions](#update-task-permissions).
| Tool name | Description |
| ------------------------- | -------------------------------------------------------------------------- |
| `git_push` | Pushes committed changes to the remote Git repository. |
| `git_commit` | Commits staged changes to the local Git repository. |
| `run_pipeline` | Triggers execution of a pipeline. |
| `query_warehouse` | Executes a read-only SQL query against the data warehouse. |
| `edit_file` | Edits file content via find-and-replace. |
| `create_file` | Creates a new file. |
| `delete_file` | Permanently deletes a file. |
| `copy_file` | Copies a file or folder to a new location. |
| `rename_file` | Renames or moves a file or folder. |
| `ask_user_question` | Asks the user structured questions with multiple-choice options. |
| `sample_component` | Samples rows from an existing pipeline component. |
| `enter_plan_mode` | Switches the agent to PLAN mode for research and design. |
| `exit_plan_mode` | Presents a plan for user review and switches back to ACT mode. |
| `create_custom_connector` | Initiates the custom connector creation flow for unsupported data sources. |