curl -X POST "https://app.runtm.com/api/cloud/v1/agents" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Donna",
"description": "GTM research agent",
"system_instructions": "Be terse. Prefer PRs over prose.",
"default_template": "gtm-machine",
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"]}
}'
runtm-api agents create --name Donna \
--instructions 'Be terse. Prefer PRs over prose.' \
--template gtm-machine \
--evaluator-criteria '{"objective":"Ship weekly lists","checks":["lists posted"]}'
{
"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. Prefer PRs over prose.",
"default_template": "gtm-machine",
"default_agent": null,
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"], "version": 1},
"economics": null
}
Agents
Create Agent
Create a roster agent
POST
/
api
/
v1
/
agents
curl -X POST "https://app.runtm.com/api/cloud/v1/agents" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Donna",
"description": "GTM research agent",
"system_instructions": "Be terse. Prefer PRs over prose.",
"default_template": "gtm-machine",
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"]}
}'
runtm-api agents create --name Donna \
--instructions 'Be terse. Prefer PRs over prose.' \
--template gtm-machine \
--evaluator-criteria '{"objective":"Ship weekly lists","checks":["lists posted"]}'
{
"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. Prefer PRs over prose.",
"default_template": "gtm-machine",
"default_agent": null,
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"], "version": 1},
"economics": null
}
Creates a named agent headlessly. Triggers (Slack, GitHub, Linear, Email) are bound afterwards through their integration endpoints; a trigger-less agent is valid and can be launched directly from sessions.
Required scope:
integrations:write
Headers
string
required
Bearer token.
string
Organization ID. Omit for a personal agent.
Request Body
string
required
Display name (max 200 characters).
string
Short description (max 2000 characters).
object
Avatar descriptor, for example
{"kind": "icon", "icon": "bot", "color": "blue"}.string
Instructions injected into every session the agent runs (max 20000 characters).
string
Org template slug sessions launch from.
string
Coding agent harness, for example
claude-code or codex.object
Evaluation rubric:
{"objective": "...", "checks": ["..."]}. The server manages the version field.object
Task values and budget.
budget.monthly_usd_cap must be a number greater than or equal to zero when present.Response
The created agent object with status201.
curl -X POST "https://app.runtm.com/api/cloud/v1/agents" \
-H "Authorization: Bearer runtm_xxx" \
-H "X-Organization-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Donna",
"description": "GTM research agent",
"system_instructions": "Be terse. Prefer PRs over prose.",
"default_template": "gtm-machine",
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"]}
}'
runtm-api agents create --name Donna \
--instructions 'Be terse. Prefer PRs over prose.' \
--template gtm-machine \
--evaluator-criteria '{"objective":"Ship weekly lists","checks":["lists posted"]}'
{
"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. Prefer PRs over prose.",
"default_template": "gtm-machine",
"default_agent": null,
"evaluator_criteria": {"objective": "Ship weekly lists", "checks": ["lists posted"], "version": 1},
"economics": null
}