Agents API

An agent is a job Dash runs for a business: chase late returns every evening, email who owes a balance every Monday, send the review request the day after. The Agents API lists, creates, updates, runs and switches off those jobs. It also reads and writes each job as a sequence, the steps the owner sees, each with a time, a channel, the message that goes out and whether it runs on its own or waits for an OK.

Scopes

Scope	Allows
agents:read	List agents, read one, read its sequence and run history
agents:write	Create, update, run, switch on or off, replace the sequence, approve or reject a step waiting for an OK

Endpoints

Method	Path	What it does
GET	/v1/agents	List the business's agents. Pass enabled=true or enabled=false to filter
GET	/v1/agents/{id}	One agent, including its sequence and mode
POST	/v1/agents	Create an agent as a draft (is_enabled false)
PUT	/v1/agents/{id}	Update name, description, instructions, tools, trigger, on/off
DELETE	/v1/agents/{id}	Delete an agent
GET	/v1/agents/{id}/sequence	The job as a sequence
PUT	/v1/agents/{id}/sequence	Replace the steps, and optionally switch between ask and auto
POST	/v1/agents/{id}/run	Run it now
GET	/v1/agents/{id}/runs	Run history
GET	/v1/agents/{id}/runs/{runId}	One run with its steps
POST	/v1/agents/{id}/runs/{runId}/actions/{actionId}/approve	Approve a step waiting for an OK
POST	/v1/agents/{id}/runs/{runId}/actions/{actionId}/reject	Reject it
GET	/v1/agents/{id}/chat	The agent's chat, its next runs and any pause
POST	/v1/agents/{id}/skips	Skip its runs on one day, or put them back
POST	/v1/agents/{id}/pause	Pause it until a day, or start it again

The agent object

{
  "id": 42,
  "name": "Chase late returns",
  "description": "Every evening, text anyone who has not brought their gear back.",
  "trigger_type": "schedule",
  "trigger_config": { "frequency": "daily", "time": "18:00" },
  "tools": ["get_late_returns", "send_sms_template_to_booking"],
  "tool_approval_modes": { "send_sms_template_to_booking": "approval_required" },
  "is_enabled": false,
  "mode": "ask",
  "sequence": [
    { "tool": "get_late_returns", "when": "Every day at 6:00pm", "channel": "check", "title": "Look up late returns", "message": null, "gate": "none", "locked": true, "ask_reason": null, "branch": null },
    { "tool": "send_sms_template_to_booking", "when": "Then", "channel": "text", "title": "Text the customer about a booking", "message": null, "gate": "ask", "locked": true, "ask_reason": "goes to your customers", "branch": null }
  ],
  "last_run_at": null,
  "next_run_at": "2026-10-16T18:00:00+11:00",
  "last_run_status": null,
  "total_runs": 0
}

trigger_type is one of manual, schedule, event or weather_threshold.

mode is ask when every step that changes something and can be switched waits for an OK, and auto when those steps run on their own. Steps that take money, can't be undone or reach a customer always ask, whatever the mode. See Sequences for the step fields and these rules.

Chat, skips and pauses

Each agent has one chat, shared by everyone in the business who manages agents. Its runs appear in it by time, next to what people asked and what the agent answered.

GET /v1/agents/{id}/chat (agents:read) returns the newest 30 items, oldest first, plus the next five runs. When has_more is true, pass the first item's at as before to get the 30 items above it:

{
  "agent_id": 42,
  "name": "Morning Briefing",
  "can_message": false,
  "paused_until": null,
  "coming_up": [
    { "at": "2026-10-19T11:00:00+00:00", "date": "2026-10-19", "when": "Monday 7:00am", "day": "Tomorrow", "skipped": false }
  ],
  "items": [
    { "kind": "run", "at": "2026-10-18T10:00:00+00:00", "run_id": 108, "status": "completed", "outcome": "20 late returns need cleanup" },
    { "kind": "message", "at": "2026-10-18T12:14:00+00:00", "role": "user", "author": "Sarah", "content": "Which late returns should I chase first?", "cards": [], "steps": [] }
  ],
  "has_more": false
}

GET /v1/agents/{id}/chat?before=2026-10-18T10:00:00Z reads the page above. date is in the business's own calendar. A skipped run stays in coming_up with skipped: true, so it can be put back.

POST /v1/agents/{id}/skips (agents:write) skips the runs on one day:

{ "date": "2026-10-19" }

Send "undo": true with the same date to put them back. An agent that runs every few minutes can't skip a day; pause it instead.

POST /v1/agents/{id}/pause (agents:write) pauses the agent until a day, after today in the business's calendar. It runs again on its own from that day:

{ "until": "2026-10-22" }

Send { "resume": true } to start it again now. Both return 422 with a message when the day isn't valid.