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. Stored as a prompt component on the baseline manifest, so later prompt edits show up as drift.

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.