Skip to main content
Agents are the workers that execute your tasks. While Miteos manages agent lifecycle automatically, the Agents API gives you fine-grained runtime control — you can pause an agent mid-flight to inspect its progress, send corrective guidance, or approve high-stakes actions before they are carried out. Agent IDs are returned in the agents array of a task object (see GET /tasks/{id}).
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.

​
Agent object

​
id
string
Unique agent identifier, prefixed agnt_.
​
task_id
string
The task this agent belongs to.
​
type
string
Specialisation of the agent: researcher, builder, analyst, trader, email, or social.
​
status
string
Current state: idle, thinking, acting, waiting, complete, or error.
​
current_tool
string
The tool being executed at this moment, if any (e.g. web_search, code_exec, send_email).
​
progress
integer
Estimated task completion percentage, 0–100.

​
Approval workflow

When autonomy_level is below 100, agents pause and request human approval before taking high-consequence actions such as sending emails, making purchases, or deploying code. The flow works as follows:
  1. The agent reaches a decision point and transitions to waiting status.
  2. Miteos emits an approval.required event via webhook (or you can poll GET /tasks/{id} and inspect agent status).
  3. You call POST /agents/{id}/approve/{approval_id} with approved: true or false.
  4. If approved, the agent continues. If rejected (and an optional reason is supplied), the agent revises its approach.
Subscribe to the approval.required webhook event to receive real-time notifications instead of polling. See the Webhooks documentation for setup instructions.

​
POST /agents/{id}/pause

Pause a running agent. The agent completes its current atomic tool call (e.g. finishes a web request in flight) and then suspends. Use POST /agents/{id}/resume to continue.

​
Path parameters

​
id
string
required
The unique agent ID to pause (e.g. agnt_01hwxyz9r4m7nk2tsd6pvqcb).

​
Example request

curl -X POST "https://api.miteos.com/v1/agents/agnt_01hwxyz9r4m7nk2tsd6pvqcb/pause" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx"

​
Example response

{
  "id": "agnt_01hwxyz9r4m7nk2tsd6pvqcb",
  "status": "paused",
  "message": "Agent paused successfully."
}

​
POST /agents/{id}/resume

Resume an agent that is currently paused. The agent picks up from where it left off.

​
Path parameters

​
id
string
required
The unique agent ID to resume.

​
Example request

curl -X POST "https://api.miteos.com/v1/agents/agnt_01hwxyz9r4m7nk2tsd6pvqcb/resume" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx"

​
Example response

{
  "id": "agnt_01hwxyz9r4m7nk2tsd6pvqcb",
  "status": "acting",
  "message": "Agent resumed successfully."
}

​
POST /agents/{id}/cancel

Permanently stop an agent. Unlike pause, cancellation cannot be undone — the agent is terminated and any work in progress is discarded. Other agents in the same task continue running.

​
Path parameters

​
id
string
required
The unique agent ID to cancel.
Cancelling an individual agent does not cancel the parent task. If you need to stop all work, use POST /tasks/{id}/cancel instead.

​
Example request

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

​
Example response

{
  "id": "agnt_01hwxyz9r4m7nk2tsd6pvqcb",
  "status": "cancelled",
  "message": "Agent cancelled successfully."
}

​
POST /agents/{id}/guide

Send a real-time guidance message to a running or paused agent. Use this to steer the agent mid-task — for example, to correct its approach, add context, or narrow the scope of its work. The agent incorporates your message into its next reasoning step.

​
Path parameters

​
id
string
required
The unique agent ID to guide.

​
Request body

​
message
string
required
The guidance message to deliver to the agent. Write it as a clear instruction or correction, as if speaking directly to the agent.

​
Example request

curl -X POST "https://api.miteos.com/v1/agents/agnt_01hwxyz9r4m7nk2tsd6pvqcb/guide" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Focus only on open-source databases with a permissive licence (MIT or Apache 2.0). Ignore commercial offerings."
  }'

​
Example response

{
  "id": "agnt_01hwxyz9r4m7nk2tsd6pvqcb",
  "status": "thinking",
  "message": "Guidance received. Agent is incorporating your instructions."
}

​
POST /agents/{id}/approve/{approval_id}

Respond to an agent’s approval request. When an agent is in waiting status with a pending approval, call this endpoint to approve or reject the proposed action. Rejecting with a reason helps the agent understand what alternative approach to take.

​
Path parameters

​
id
string
required
The unique agent ID awaiting approval.
​
approval_id
string
required
The unique approval request ID. This is delivered in the approval.required webhook event payload and is also visible in the task object.

​
Request body

​
approved
boolean
required
Set to true to allow the agent to proceed with the proposed action, or false to reject it.
​
reason
string
Optional explanation for a rejection. The agent uses this to revise its plan before attempting an alternative approach.

​
Example request

curl -X POST "https://api.miteos.com/v1/agents/agnt_01hwxyz9r4m7nk2tsd6pvqcb/approve/appr_01hwxyzd4e1rm0uf9tw5jnbyg" \
  -H "Authorization: Bearer mt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": false,
    "reason": "Do not send the email yet — the copy needs review. Draft it as a deliverable file instead."
  }'

​
Example response

{
  "id": "agnt_01hwxyz9r4m7nk2tsd6pvqcb",
  "status": "thinking",
  "message": "Approval decision recorded. Agent is revising its approach."
}