Create an agent role

POST/api/v1/agents/roles

Add an agent to the team. The claude_code and codex engines run on the firm's own subscriptions and are for DayZero staff only (AGENT_003). Business admins only.

Operation ID: agents_create_role·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: AgentRoleCreate

namestringrequired

Short role name, e.g. Bookkeeper.

titlestring

instructionsstring

Standing instructions (markdown).

skillsarray · AgentSkillAgentSkill

5 fields

namestringrequired
descriptionstring
bodystring: Markdown the role reads when the skill applies.
enabledboolean
learnedboolean

enginestring

native runs DayZero's own loop on Gemini (every role); claude_code and codex run the firm's CLIs on its subscriptions (DayZero staff only).

One of: native, claude_code, codex

modelstring

Model id for the engine; null = the engine's default (google/gemini-4-argon).

scopestring

read never proposes; changes files gated writes as proposed changes.

One of: read, changes

allowed_toolsarray · string

Tool access: tool names, group:<mount> (a whole tool group) and server:<handle> (a connected MCP server); null = every tool its scope allows. AGENT_026 for a token it cannot hold.

paramsobject

spend_cap_usd_monthstring

Monthly spend cap in USD; new runs refuse above it and a run in flight stops before its next turn once it is reached.

max_cost_usd_runstring

Default cost limit of one run in USD; null = no per-run limit.

browserboolean

Drives a real browser with saved logins (Claude Code or Codex only).

library_keystring

personaAgentPersonaUpdate

Face and vibe; what is left out gets the first color and body no other role on the team has, and the steady vibe.

Responses

201Successful Response

Schema: SuccessEnvelope_AgentRoleOut_

successboolean
messagestring
codestring
dataAgentRoleOut

400Bad Request - Invalid input

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

401Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

403Forbidden - Insufficient permissions

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

409Conflict - Resource already exists or is in an incompatible state

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

422Validation Error

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

Code samples

POST/api/v1/agents/roles

bash

curl -X POST 'https://api.ondayzero.com/api/v1/agents/roles' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string"
}'