The API guide

The MyDeepAgents API is a JSON API over HTTPS. Every resource lives at a predictable address under /v1, with standard verbs and one error shape, so once you have made one call you know how to make the rest.

The API describes itself. Its OpenAPI 3.1 document is generated from the code that answers the requests, so the reference in these docs, and any client you generate from it, always match the API that is running.

Every call carries a secret key in the Authorization header. A key belongs to a service account: an identity for software rather than a person, so a key keeps working when people join or leave your team.

Authorization: Bearer mda_live_k7m2p9qa3tq8v1zc_…

What a key looks like

A key has three parts. Only the last is secret, and MyDeepAgents keeps only a hash of it, so a lost key can't be shown again: revoke it and make a new one.

What a key may do

A key can do what its service account's role allows, narrowed to the scopes you chose for the key. Scopes are permission names such as agent.view or workflow.run, and every endpoint in the reference shows the one it needs.

A few permissions belong to the organization's owner alone and can't be given to a key's role: encryption keys, storage, delegations and full exports.

Keep keys safe

• Call the API from servers only. A secret key never belongs in a browser or a mobile app; to talk to visitors on a website, use a widget and its publishable key.
• Give each integration its own key with the fewest scopes it needs, so you can revoke one without touching the others.
• Limit a key to your servers' addresses with an IP allowlist. Calls from anywhere else get 403 ip_not_allowed.
• Give keys that are only needed for a while an expiry date.

When a key is refused

Some endpoints are for people only: your own profile and sign-in security, accepting an invitation, and signing up. They refuse keys, so they are not in the reference.

Send JSON with Content-Type: application/json. A body with a field the API doesn't know is refused with 422, so a typo never passes silently.

ID prefixes you will meet

• agt_Agent
• wf_Workflow
• wgt_Widget
• run_Agent run
• wfr_Workflow run
• trg_Trigger
• evt_Trigger event
• con_Connection
• mcp_MCP server
• ws_Workspace
• usr_Person
• sa_Service account

Request IDs

Every answer carries an X-Request-Id header, and every error repeats it as request_id. Send your own (up to 64 letters, digits, dots, colons, dashes and underscores) to follow one call through your logs and ours; anything else is replaced with a new one.

{
  "type": "https://docs…/errors/validation_failed",
  "title": "The request is not valid.",
  "status": 422,
  "code": "validation_failed",
  "detail": "1 field is not valid.",
  "request_id": "req_01jc8z6y4m3k9q2w5e7r1t0vbn",
  "errors": [
    {
      "path": "/definition/spec/model/id",
      "code": "model_unavailable",
      "message": "Model 'gpt-9' is not available here.",
      "hint": "Pick one of the models in GET /v1/models."
    }
  ]
}

Codes you are most likely to meet

Every error code, with what it means and what to do

Retry safely

• Retry 429 and 503 with exponential back-off, waiting at least retry_after seconds when the answer gives it.
• Retry network errors the same way. For run starts, send the same Idempotency-Key again, so a retry can never start a second run.
• Don't retry other 4xx answers: the same request will get the same answer.

{
  "object": "list",
  "data": [
    {
      "id": "agt_01jctdbahw9btk5p831xs974yq",
      "object": "agent",
      "name": "Support triage",
      "…": "…"
    }
  ],
  "has_more": true,
  "next_cursor": "b2Zmc2V0OjUwfGFndF8wMWpj…"
}

Read every page

CURSOR=""
while : ; do
  PAGE=$(curl -s "https://api.mydeepagents.com/v1/agents?limit=200&cursor=$CURSOR" \
    -H "Authorization: Bearer $MDA_API_KEY")
  echo "$PAGE" | jq -r '.data[].name'
  [ "$(echo "$PAGE" | jq -r '.has_more')" = "true" ] || break
  CURSOR=$(echo "$PAGE" | jq -r '.next_cursor')
done

Starting a run is the one call you must never make twice by accident: a retried request could run an agent, and spend money, a second time. So both run starts require an Idempotency-Key header; without one the answer is 400.

• Use a fresh value for each run, such as a UUID, up to 255 characters.
• Send the same key when you retry. For 24 hours the API answers with the run it already started and adds Idempotent-Replayed: true.
• A key reused with a different body is refused with 422 idempotency_key_reuse. If the first request is still being handled, the retry waits for it and then gets the same answer.

Keys are kept per organization and per caller, so two integrations can never collide.

A run is one piece of work by an agent or a workflow. Starting one answers 202 at once with the run queued; the work happens after the answer, so your request never waits on a model.

Start an agent run

curl -X POST "https://api.mydeepagents.com/v1/agents/agt_01jctdbahw9btk5p831xs974yq/runs" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "message": "Summarise today'\''s open tickets."
    },
    "target": "live"
  }'

{
  "id": "run_01jcr77659p6hws1zjqkthay73",
  "object": "run",
  "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h",
  "alias": "live",
  "state": "queued",
  "trigger": "api",
  "is_test": false,
  "cost_micro_usd": 0,
  "steps_used": 0,
  "created_at": "2026-11-10T09:30:00.000Z",
  "row_version": 1
}

Follow an agent run by streaming its events, below, or by reading GET /v1/runs/{id} until its state is final.

Workflow runs

A workflow run starts the same way, at POST /v1/workflows/{id}/runs with an Idempotency-Key; its input is checked against the workflow's input schema. Follow it by reading GET /v1/workflow_runs/{id}, or let a webhook endpoint tell you with workflow_run.state_changed. Stop it with POST /v1/workflow_runs/{id}/cancel. Workflow runs don't stream yet.

GET /v1/runs/{id}/events sends the run as it happens, as server-sent events. Each event has a type and a JSON payload, and the answer's text arrives piece by piece as the model writes it.

curl -N "https://api.mydeepagents.com/v1/runs/run_01jcr77659p6hws1zjqkthay73/events" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Accept: text/event-stream"

What a stream looks like

id: 1762767000123-0
event: run.started
data: {"run_id":"run_01jcr77659p6hws1zjqkthay73","agent_version_id":"agv_01jc7jt62eapjyt621bszf6wrs"}

id: 1762767000456-0
event: tool.started
data: {"run_id":"run_01jcr77659p6hws1zjqkthay73","call_id":"call_1","tool":"crm.search_contacts","status":"requested"}

id: 1762767001789-0
event: tool.finished
data: {"run_id":"run_01jcr77659p6hws1zjqkthay73","call_id":"call_1","tool":"crm.search_contacts","status":"ok","ms":412}

id: 1762767002010-0
event: message.delta
data: {"run_id":"run_01jcr77659p6hws1zjqkthay73","message_id":"msg_01jc7qh04g97wt3q32g0wny446","index":0,"text":"Three tickets"}

: keep-alive

id: 1762767003900-0
event: run.completed
data: {"run_id":"run_01jcr77659p6hws1zjqkthay73","status":"completed","usage":{"steps":3,"cost_micro_usd":4210,"input_tokens":1820,"output_tokens":240},"error":null}

Events

How to read a stream

• Reconnect with the last id you received in Last-Event-ID; the stream carries on right after it.
• A comment line arrives every 15 seconds so proxies keep the connection open. Ignore lines that start with a colon.
• The live copy lasts an hour after the run's last event. After that you get 410 stream_expired: read the finished run instead.
• Message events carry the answer's text, so only callers with run.view_content receive them. Everyone else still sees the run's shape: tools, approvals and the end.
• New event types can appear inside v1. Skip types you don't know.

Everything in v1 only grows. New endpoints, new optional fields, new values and new event types can appear, but nothing you rely on is renamed, retyped or removed. A change that would break you comes as v2, with v1 kept running beside it.

• Ignore fields you don't recognise.
• Handle unknown values, for example by showing them as they are.
• Don't depend on the order of fields in JSON.