Skip to main content
POST /api/v2/agents creates a private Agent in your organization’s Developer account. Switch to that account before registering an Agent. If your organization does not have one, create it from the organization’s Accounts screen or with save_account in the organization account. Supply a unique idempotencyKey; repeating the exact request returns the original Agent with created: false. Build an agent offers sales and creative Agents. To set up a buyer agent, use Buyer-agent credentials instead. Sales Agents require salesMode of WHOLESALE, COMPOSING, or BOTH. All non-Sales Agents must set salesMode to null. Choose an existing claimed operator, or provide a new operator name to create it atomically with the Agent. Creation never publishes an Agent or connects a Source. Signal and Outcome are legacy REST roles: this endpoint accepts them for compatibility, but Build an agent does not offer them. The organization MCP surface also provides open_create_agent_task to open the bounded Create Agent Task, and open_agent_page to open a created Agent.
This is available only to directly authenticated Developer account admins. Service-token and delegated sessions cannot create Agents.

​
Request

​
Parameters

​
Response

New creation returns 201; an exact idempotent replay returns 200.
href is a handoff target for the canonical Agent Page. It is not a public Agent URL.

​
Errors

  • 400 VALIDATION_ERROR — the request is malformed, a name is empty, the role is not a supported stored role, the role and sales mode are incompatible, or the operator union is invalid.
  • 403 ACCESS_DENIED — the caller is not a directly authenticated Developer account admin, or the active account is not a Developer account. Switch to your organization’s Developer account, or create one from Accounts or with save_account in the organization account.
  • 404 NOT_FOUND — Organization Agents is unavailable to the caller’s enrolled organization, or the requested existing operator is not owned and claimed.
  • 409 CONFLICT — the idempotency key was previously used with different input. A duplicate active NEW operator name in your organization also returns this conflict; select the existing claimed operator instead.
See Errors for the full error contract.

​
Apostra-mapped operators awaiting claim

Apostra sometimes maps a known operator to your organization before anyone on your team explicitly claims it — for example, from an audited legacy integration. A mapped-but-unclaimed operator shows up in GET /api/v2/agents as Apostra mapped · unclaimed, and any Agent behind it cannot receive production revisions, certification, or new connections until an organization account admin claims it. Claiming preserves the operator’s identity, revisions, bindings, and history — it never creates a second copy. Claim it with:
operator.kind: "EXISTING" for a Create Agent request only accepts an already-claimed operator (404 NOT_FOUND otherwise per the Errors table above) — this is deliberate: creating a new Agent under an unclaimed operator would silently duplicate an identity Apostra already knows about. Claim the mapped operator first, then create the Agent under it.

​
MCP tools

open_create_agent_task opens the bounded Create Agent Task for a Developer account admin. After creation, open_agent_page opens the private Agent Page by agentId. Agents already registered in other account types keep their existing page and management access during this transition.