Jump toApprovals

Approvals

Tool calls waiting for a person to say yes or no.

get/v1/approvals

List approvals

Needs run.approve

The inbox: pending tasks by default, newest first.

Query parameters

statestring
One ofpendingapprovedrejectedexpiredcancelledDefault"pending"
run_idstring
workspace_idstring
limitinteger
Default50at least 1at most 200
cursorstring

Response200

objectstring
list
dataApproval[]
17 fields
- idstring
- objectstring
  approval
- created_atstring or null
- data_classstring
- decided_atstring or null
- decided_bystring or null
- decision_sourcestring or null
- due_atstring or null
- kindstring
  One oftool_approvalworkflow_approvalworkflow_form
- row_versioninteger
- run_idstring
- run_kindstring
  One ofagentworkflow
- statestring
  One ofpendingapprovedrejectedexpiredcancelled
- titlestring
- workspace_idstring
- content_visibleboolean
  Defaultfalse
- requestany
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/approvals?limit=20" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "apr_01jcdy8knavmbznwavrdg025zc",
      "object": "approval",
      "content_visible": false,
      "created_at": "2026-11-10T09:30:00.000Z",
      "data_class": "data class",
      "decided_at": "2026-11-10T09:30:00.000Z",
      "decided_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
      "decision_source": "decision source",
      "due_at": "2026-11-10T09:30:00.000Z",
      "kind": "tool_approval",
      "request": {},
      "row_version": 4,
      "run_id": "run_01jcr77659p6hws1zjqkthay73",
      "run_kind": "agent",
      "state": "pending",
      "title": "Support triage",
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

get/v1/approvals/{approval_id}

Get approval

Needs run.approve

The task, and what it asks (the tool and its arguments) when the caller may see content (run.view_content); otherwise content_visible is false.

Path parameters

approval_idstringRequired

Response200

idstring
objectstring
approval
created_atstring or null
data_classstring
decided_atstring or null
decided_bystring or null
decision_sourcestring or null
due_atstring or null
kindstring
One oftool_approvalworkflow_approvalworkflow_form
row_versioninteger
run_idstring
run_kindstring
One ofagentworkflow
statestring
One ofpendingapprovedrejectedexpiredcancelled
titlestring
workspace_idstring
content_visibleboolean
Defaultfalse
requestany

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/approvals/apr_01jcdy8knavmbznwavrdg025zc" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "apr_01jcdy8knavmbznwavrdg025zc",
  "object": "approval",
  "content_visible": false,
  "created_at": "2026-11-10T09:30:00.000Z",
  "data_class": "data class",
  "decided_at": "2026-11-10T09:30:00.000Z",
  "decided_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
  "decision_source": "decision source",
  "due_at": "2026-11-10T09:30:00.000Z",
  "kind": "tool_approval",
  "request": {},
  "row_version": 4,
  "run_id": "run_01jcr77659p6hws1zjqkthay73",
  "run_kind": "agent",
  "state": "pending",
  "title": "Support triage",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

post/v1/approvals/{approval_id}/decision

Decide approval

Needs run.approve

Path parameters

approval_idstringRequired

Request bodyDecisionBody

decisionstringRequired
One ofapprovedrejected
commentstring or null
at most 2000 characters

Response200

idstring
objectstring
approval
created_atstring or null
data_classstring
decided_atstring or null
decided_bystring or null
decision_sourcestring or null
due_atstring or null
kindstring
One oftool_approvalworkflow_approvalworkflow_form
row_versioninteger
run_idstring
run_kindstring
One ofagentworkflow
statestring
One ofpendingapprovedrejectedexpiredcancelled
titlestring
workspace_idstring
content_visibleboolean
Defaultfalse
requestany

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/approvals/apr_01jcdy8knavmbznwavrdg025zc/decision" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "comment",
    "decision": "approved"
  }'

Response · 200

JSON

{
  "id": "apr_01jcdy8knavmbznwavrdg025zc",
  "object": "approval",
  "content_visible": false,
  "created_at": "2026-11-10T09:30:00.000Z",
  "data_class": "data class",
  "decided_at": "2026-11-10T09:30:00.000Z",
  "decided_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
  "decision_source": "decision source",
  "due_at": "2026-11-10T09:30:00.000Z",
  "kind": "tool_approval",
  "request": {},
  "row_version": 4,
  "run_id": "run_01jcr77659p6hws1zjqkthay73",
  "run_kind": "agent",
  "state": "pending",
  "title": "Support triage",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.

Talk to us Read the API guide