curl -X PATCH "https://app.runtm.com/api/cloud/v1/agents/a1b2c3d4-0000-0000-0000-000000000000" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{"economics": {"budget": {"monthly_usd_cap": 50}}}'
# Only the orchestrator agent may launch it, and each delegation needs an
# approval from the ops group. `humans: false` is what shuts people out for
# good: naming only an agent already blocks ordinary members, but org admins
# keep their override under the `role` access model.
curl -X PATCH "https://app.runtm.com/api/cloud/v1/agents/a1b2c3d4-0000-0000-0000-000000000000" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{"callable_by": {"humans": false, "groups": [],
"agents": [{"agent_id": "b1c506b1-...", "approval": {"required_team_id": "team_ops"}}]}}'
runtm-api agents update a1b2c3d4-0000-0000-0000-000000000000 \
--economics '{"budget":{"monthly_usd_cap":50}}'
# Clear the default template (explicit null, fans out to triggers)
runtm-api agents update a1b2c3d4-0000-0000-0000-000000000000 --clear-template
{
"id": "a1b2c3d4-0000-0000-0000-000000000000",
"organization_id": "org_abc123",
"name": "Donna",
"description": "GTM research agent",
"avatar": null,
"avatar_image_url": null,
"system_instructions": "Be terse.",
"default_template": "gtm-machine",
"default_agent": "claude-code",
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"], "version": 2},
"economics": {"budget": {"monthly_usd_cap": 50}}
}
Agents
Update Agent
Edit a roster agent; omitted fields are left unchanged
PATCH
/
api
/
v1
/
agents
/
{agent_id}
curl -X PATCH "https://app.runtm.com/api/cloud/v1/agents/a1b2c3d4-0000-0000-0000-000000000000" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{"economics": {"budget": {"monthly_usd_cap": 50}}}'
# Only the orchestrator agent may launch it, and each delegation needs an
# approval from the ops group. `humans: false` is what shuts people out for
# good: naming only an agent already blocks ordinary members, but org admins
# keep their override under the `role` access model.
curl -X PATCH "https://app.runtm.com/api/cloud/v1/agents/a1b2c3d4-0000-0000-0000-000000000000" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{"callable_by": {"humans": false, "groups": [],
"agents": [{"agent_id": "b1c506b1-...", "approval": {"required_team_id": "team_ops"}}]}}'
runtm-api agents update a1b2c3d4-0000-0000-0000-000000000000 \
--economics '{"budget":{"monthly_usd_cap":50}}'
# Clear the default template (explicit null, fans out to triggers)
runtm-api agents update a1b2c3d4-0000-0000-0000-000000000000 --clear-template
{
"id": "a1b2c3d4-0000-0000-0000-000000000000",
"organization_id": "org_abc123",
"name": "Donna",
"description": "GTM research agent",
"avatar": null,
"avatar_image_url": null,
"system_instructions": "Be terse.",
"default_template": "gtm-machine",
"default_agent": "claude-code",
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"], "version": 2},
"economics": {"budget": {"monthly_usd_cap": 50}}
}
Partial update. Two fields have fan-out semantics: editing
default_template or default_agent also updates every trigger integration linked to this agent (the roster row is the source of truth for defaults).
Required scope: integrations:write
Path Parameters
string
required
The agent ID.
Request Body
All fields optional; omitted fields are unchanged.string
New display name.
string
New description.
object
New avatar descriptor.
string
New system instructions.
string | null
New default template. Send an explicit
null to clear it. Fans out to linked triggers either way.string
New coding agent harness. Only concrete values apply; it cannot be cleared with null.
object
Replacement rubric. The server bumps
version on every edit so run grades record which rubric produced them.object
Replacement task values and budget.
string | null
Group that may edit, disable or delete the agent. Send
null for everyone in the org.object
Who may launch it:
{"humans": true, "groups": ["team_ops"], "agents": [{"agent_id": "...", "approval": {"required_team_id": "team_ops"}}]}. Both lists empty = anyone in the org; naming anyone closes it to exactly those. humans: false bars every person regardless, including org admins. See Trigger a subagent.Response
The updated agent object.curl -X PATCH "https://app.runtm.com/api/cloud/v1/agents/a1b2c3d4-0000-0000-0000-000000000000" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{"economics": {"budget": {"monthly_usd_cap": 50}}}'
# Only the orchestrator agent may launch it, and each delegation needs an
# approval from the ops group. `humans: false` is what shuts people out for
# good: naming only an agent already blocks ordinary members, but org admins
# keep their override under the `role` access model.
curl -X PATCH "https://app.runtm.com/api/cloud/v1/agents/a1b2c3d4-0000-0000-0000-000000000000" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{"callable_by": {"humans": false, "groups": [],
"agents": [{"agent_id": "b1c506b1-...", "approval": {"required_team_id": "team_ops"}}]}}'
runtm-api agents update a1b2c3d4-0000-0000-0000-000000000000 \
--economics '{"budget":{"monthly_usd_cap":50}}'
# Clear the default template (explicit null, fans out to triggers)
runtm-api agents update a1b2c3d4-0000-0000-0000-000000000000 --clear-template
{
"id": "a1b2c3d4-0000-0000-0000-000000000000",
"organization_id": "org_abc123",
"name": "Donna",
"description": "GTM research agent",
"avatar": null,
"avatar_image_url": null,
"system_instructions": "Be terse.",
"default_template": "gtm-machine",
"default_agent": "claude-code",
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"], "version": 2},
"economics": {"budget": {"monthly_usd_cap": 50}}
}