Tasks API: Create, Monitor, and Cancel Agent Tasks

Tasks are the core unit of work in Miteos. When you create a task, the platform spins up one or more AI agents to carry out your prompt autonomously — researching, building, analysing, or executing actions on your behalf. Each task moves through a lifecycle from pending all the way to complete or failed, and produces deliverable files you can download when the work is done.

Every request must include an Authorization: Bearer <token> header. Use a mt_live_ prefixed token for production and a mt_test_ prefixed token for sandbox testing.

POST /tasks

Create a new task and dispatch agents to fulfil the prompt. The response returns immediately with a pending task object — agents begin working asynchronously.

Request body

prompt

string

required

The natural-language instruction that agents will act on. Be specific: include context, constraints, and the desired output format.

config

object

Optional configuration object that controls how agents run this task.

Show config fields

config.max_agents

integer

default:3

Maximum number of agents to spawn in parallel. Accepts 1–10. Higher values can speed up complex tasks at greater credit cost.

config.autonomy_level

integer

default:70

How independently agents act before pausing for human approval. Range 0–100. At 0, agents request approval for every action; at 100, they proceed without interruption.

config.auto_deploy

boolean

default:false

When true, any application built during the task is automatically deployed to the target specified in deploy_target.

config.deploy_target

string

Deployment platform to use when auto_deploy is true. One of vercel, netlify, cloudflare, or expo.

Example request

curl -X POST https://api.miteos.com/v1/tasks \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Research the top 5 open-source vector databases and produce a comparison report as a Markdown file.",
    "config": {
      "max_agents": 3,
      "autonomy_level": 70,
      "auto_deploy": false
    }
  }'

Example response

{
  "id": "task_01hwxyz4k8p3mq9rbn2csved",
  "status": "pending",
  "prompt": "Research the top 5 open-source vector databases and produce a comparison report as a Markdown file.",
  "config": {
    "max_agents": 3,
    "autonomy_level": 70,
    "auto_deploy": false,
    "deploy_target": null
  },
  "created_at": "2025-01-15T10:23:44Z"
}

GET /tasks

Return a paginated list of all tasks in your account. Filter by status to monitor active or completed work.

Query parameters

status

string

Filter results to tasks with a specific status. One of pending, planning, running, paused, complete, failed, or cancelled.

limit

integer

default:20

Number of tasks to return per page. Maximum 100.

offset

integer

default:0

Number of tasks to skip before starting the page. Use together with limit to paginate.

Example request

curl "https://api.miteos.com/v1/tasks?status=running&limit=20&offset=0" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx"

Example response

{
  "tasks": [
    {
      "id": "task_01hwxyz4k8p3mq9rbn2csved",
      "status": "running",
      "prompt": "Research the top 5 open-source vector databases...",
      "created_at": "2025-01-15T10:23:44Z"
    },
    {
      "id": "task_01hwab5j7n2lp8qcm3dtuew0",
      "status": "running",
      "prompt": "Build a responsive landing page for project Apex.",
      "created_at": "2025-01-15T09:11:02Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

GET /tasks/{id}

Retrieve the full details of a single task, including its current agent statuses, accumulated cost, and deliverable count.

Path parameters

string

required

The unique task ID returned when the task was created (e.g. task_01hwxyz4k8p3mq9rbn2csved).

Example request

curl "https://api.miteos.com/v1/tasks/task_01hwxyz4k8p3mq9rbn2csved" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx"

Example response

{
  "id": "task_01hwxyz4k8p3mq9rbn2csved",
  "status": "running",
  "prompt": "Research the top 5 open-source vector databases and produce a comparison report as a Markdown file.",
  "config": {
    "max_agents": 3,
    "autonomy_level": 70,
    "auto_deploy": false,
    "deploy_target": null
  },
  "agents": [
    {
      "id": "agnt_01hwxyz9r4m7nk2tsd6pvqcb",
      "type": "researcher",
      "status": "acting",
      "current_tool": "web_search",
      "progress": 45
    }
  ],
  "cost": 0.042,
  "deliverables_count": 0,
  "created_at": "2025-01-15T10:23:44Z"
}

Response fields

string

Unique task identifier.

status

string

Current lifecycle status: pending, planning, running, paused, complete, failed, or cancelled.

agents

array

Array of agent objects currently assigned to the task.

Show agent fields

agents[].id

string

Agent identifier.

agents[].type

string

Agent specialisation: researcher, builder, analyst, trader, email, or social.

agents[].status

string

Agent state: idle, thinking, acting, waiting, complete, or error.

agents[].current_tool

string

Name of the tool the agent is currently using, if any.

agents[].progress

integer

Estimated completion percentage, 0–100.

cost

number

Cumulative credit cost incurred so far for this task.

deliverables_count

integer

Number of deliverable files produced by the task so far.

POST /tasks/{id}/cancel

Stop a running or paused task immediately. All active agents are terminated and no further credits are charged. Completed work and any deliverables already produced are preserved.

Path parameters

string

required

The unique task ID to cancel.

Cancellation is irreversible. You cannot resume a cancelled task — create a new task if you need to restart the work.

Example request

curl -X POST "https://api.miteos.com/v1/tasks/task_01hwxyz4k8p3mq9rbn2csved/cancel" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx"

Example response

{
  "success": true
}

GET /tasks/{id}/deliverables

List all files produced by a completed task. Each deliverable includes metadata and a pre-signed download_url valid for one hour.

Path parameters

string

required

The unique task ID whose deliverables you want to list.

Example request

curl "https://api.miteos.com/v1/tasks/task_01hwxyz4k8p3mq9rbn2csved/deliverables" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx"

Example response

[
  {
    "id": "dlvr_01hwxyzb2c9pk5rt8nv7gmwxq",
    "name": "vector-database-comparison.md",
    "type": "text/markdown",
    "size_bytes": 14823,
    "download_url": "https://cdn.miteos.com/deliverables/dlvr_01hwxyzb2c9pk5rt8nv7gmwxq?sig=...",
    "created_at": "2025-01-15T10:47:11Z"
  },
  {
    "id": "dlvr_01hwxyzc3d0ql6su9ow8hnxyp",
    "name": "benchmark-data.csv",
    "type": "text/csv",
    "size_bytes": 3204,
    "download_url": "https://cdn.miteos.com/deliverables/dlvr_01hwxyzc3d0ql6su9ow8hnxyp?sig=...",
    "created_at": "2025-01-15T10:47:15Z"
  }
]

Response fields

string

Unique deliverable file identifier.

name

string

Original filename as saved by the agent.

type

string

MIME type of the file.

size_bytes

integer

File size in bytes.

download_url

string

Pre-signed URL for direct download. Valid for one hour from the time the list endpoint is called.

created_at

string

ISO 8601 timestamp when the agent produced the file.

GET /tasks/{id}/deliverables/{file_id}/download

Stream the binary content of a single deliverable file. The response body is the raw file — set your HTTP client to write it to disk.

Path parameters

string

required

The unique task ID that produced the deliverable.

file_id

string

required

The unique deliverable file ID (e.g. dlvr_01hwxyzb2c9pk5rt8nv7gmwxq).

The download_url included in each deliverable from GET /tasks/{id}/deliverables is a pre-signed CDN link that lets you download without an Authorization header — useful for browser-side downloads or sharing files with teammates.

Example request

curl -OJ "https://api.miteos.com/v1/tasks/task_01hwxyz4k8p3mq9rbn2csved/deliverables/dlvr_01hwxyzb2c9pk5rt8nv7gmwxq/download" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx"

The response is a binary stream with the appropriate Content-Type and Content-Disposition headers set. There is no JSON response body for this endpoint.

​POST /tasks

​Request body

​Example request

​Example response

​GET /tasks

​Query parameters

​Example request

​Example response

​GET /tasks/{id}

​Path parameters

​Example request

​Example response

​Response fields

​POST /tasks/{id}/cancel

​Path parameters

​Example request

​Example response

​GET /tasks/{id}/deliverables

​Path parameters

​Example request

​Example response

​Response fields

​GET /tasks/{id}/deliverables/{file_id}/download

​Path parameters

​Example request

POST /tasks

Request body

Example request

Example response

GET /tasks

Query parameters

Example request

Example response

GET /tasks/{id}

Path parameters

Example request

Example response

Response fields

POST /tasks/{id}/cancel

Path parameters

Example request

Example response

GET /tasks/{id}/deliverables

Path parameters

Example request

Example response

Response fields

GET /tasks/{id}/deliverables/{file_id}/download

Path parameters

Example request