Create an agent
Create an agent by registering its baseline manifest.
Returns 201 with the new agent’s id, the baseline manifest it was created
from, and how many of the requested skills were assigned. A skill that
can’t be attached — unknown id, seeded demo data, or the plan’s
linked-skill allowance used up — is reported in skills_failed
rather than failing the whole create: the agent is the thing being made
here, and losing it because one skill id was stale would be the wrong
trade. skills_failed_detail carries the reason, and for a plan refusal
an error_code the UI can key an upgrade prompt off.
skill_ids may name your own skills OR public registry skills. Attaching
a registry skill here is free on every plan (2026-08-22 pricing decision:
the moment that demonstrates the product isn’t paywalled) — the Pro+
gate applies to curating an agent’s skills afterwards, not to this. The
quantity cap is unchanged either way.
Authorizations
Enter your API key (e.g. dai_sk_test_key_001)
Cookies
Body
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.)
Lowercase letters, digits, hyphens and underscores; 1–200 chars. Becomes the agent's URL path segment and must be unique per org.
Free-text note about what this agent does.
The agent's system prompt. Stored as a prompt component on the baseline manifest, so later prompt edits show up as drift.
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.