Skip to main content
POST
Create an agent

Authorizations

Authorization
string
header
required

Enter your API key (e.g. dai_sk_test_key_001)

Headers

Authorization
string
X-Workspace-Id
string | null

Cookies

decimal_session
string | null

Body

application/json

Body of POST /api/v1/agents.

agent_name is Optional[str] here despite being REQUIRED by the contract, and that is on purpose: declaring it str would make a missing field a FastAPI 422 while an empty-string field is a 400, so the caller would have to handle two error shapes for one mistake. Optional + an explicit check in the handler routes every name problem — absent, empty, wrong shape, reserved prefix — through the same 400 with the same message field. (A genuinely non-string value, e.g. {"agent_name": 12}, is still a 422; pydantic rejects it before the handler runs.)

agent_name
string | null

Lowercase letters, digits, hyphens and underscores; 1–200 chars. Becomes the agent's URL path segment and must be unique per org.

description
string | null

Free-text note about what this agent does.

system_prompt
string | null

The agent's system prompt. Becomes version 1 of the agent's prompt object, which is what load_agent() reads and what the dashboard edits; it is also recorded as a prompt component on the baseline manifest, which goes on describing what RAN. Max 100,000 characters.

Maximum string length: 100000
pack
string | null

The role pack this agent was created from — an archetype slug from GET /api/v1/registry/packs. Version 1 of the prompt is then recorded with provenance='pack', which is what makes 'did they keep the starter?' answerable later. When system_prompt is omitted, the pack's starter prompt is used as-is.

skill_ids
string[]

Skills to attach to the new agent. Either one of your org's own skills, or any public registry skill — attaching registry skills while creating an agent is free on every plan (curating them afterwards is Pro+). Capped by the plan's linked-skill allowance; an id that is neither is reported in skills_failed.

Response

Successful Response

The response is of type Response Create Agent Api V1 Agents Post · object.