Skip to main content
POST
Propose a create (preview + confirmation token)
Same two-step contract as editing — see Propose an agent edit for the full walkthrough. The differences here: the confirm step needs no If-Match (a create has no prior state to pin), and metadata.productionAssistantId is how you anchor the new draft to a published agent — the way to edit a published agent through this API, since edits only ever land on drafts.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

tenant
string
required

Tenant whose agents you are managing. Discover the tenants your credentials cover with listMyClaudiaProjects. A tenant your credentials do not cover is indistinguishable from one that does not exist.

Body

application/json

The agent to create. config takes the shape listAssistants/getAssistant return for an existing agent of the same deployment, and must carry project. metadata accepts ONLY productionAssistantId — the id of a published agent on this tenant to anchor the new draft to.

The agent to create. config must carry project. metadata accepts only productionAssistantId.

deployment
enum<string>
required

Target deployment role: supervisor for an orchestrator agent, react for a specialist one. Any other value answers 400. There is no qna deployment to send: a knowledge-base Q&A agent is created as react with graphId set to qna_agent, and the platform derives its deployment_role: qna from that graph.

Available options:
supervisor,
react
name
string
required

Human-readable agent name.

config
object
required

The config.configurable object. Build it in the shape listAssistants/getAssistant return for an existing agent of the same deployment — read one first and follow it. Send it as a JSON OBJECT, never as a JSON-encoded string, and always carrying config.project — a propose without it is rejected with 400.

graphId
string
required

LangGraph graph id. agent is the graph both the supervisor and react deployments host, for orchestrators and regular specialists — the deployment field selects the target. qna_agent, together with deployment: react, creates a knowledge-base Q&A agent: its config carries knowledge_base_ids — ids from listMyKnowledgeBases, copied verbatim — instead of tool whitelists, and the platform reports it back with deployment_role: qna. Routing caveat: the supervisor's judge never offers a qna_agent as a routing option — a Q&A agent listed in a supervisor's agents[] is reached only through the start-with-agentic bypass on the customer's first message, not by regular routing on later turns.

description
string

This assistant's own routing description. For a sub-agent it is what supervisors use to decide when to route to it, so make it rich and specific.

metadata
object

Optional. productionAssistantId is the ONLY key this endpoint accepts — set it to anchor the created draft to a PUBLISHED agent of the same deployment on this tenant. Any other key is rejected with 422. Unlike plain createAssistant (where metadata is dropped entirely), propose-create reads and re-verifies this one key at confirm time.

Response

The confirmation contract: message (review + confirm instructions), diff (git unified format, all + lines, prompt bodies in full), preview (the final persisted state, with long prompt bodies stubbed) and confirmationId — send it back unchanged to confirmAssistantCreate.

The response is of type object.