> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt > Use this file to discover all available pages before exploring further. # Propose an agent create > First step of a safe two-step create — nothing is created yet. Send the full create body (for a knowledge-base Q&A agent: `deployment: react`, `graphId: qna_agent`, and `knowledge_base_ids` inside `config`): `config` takes the shape listAssistants and getAssistant return for an existing agent of the same `deployment`, and must carry `project`. `metadata.productionAssistantId` is the ONLY metadata key accepted here — set it to anchor the new draft to a PUBLISHED agent of the same `deployment` on this tenant, which is the pairing proposeAssistantEdits coaches you toward when a published agent has no draft yet; any other metadata key is refused. Returns `message`, `diff`, `preview` and `confirmationId`: `diff` renders the whole state as `+` lines with prompt bodies STUBBED to their real length (`[N chars — use readAssistantText]`) — the full text is exactly what you authored and is what gets created — while `preview` is that same state as it will persist (server defaults and coordinates applied), prompt bodies stubbed the same way. Review the diff, then call confirmAssistantCreate with just that confirmationId; no other body field is read. The agent is ALWAYS created as a DRAFT — a human reviews and publishes it in the ClaudIA app, and this surface has no opt-out. Same two-step contract as editing — see [Propose an agent edit](/api-reference/claudia/endpoints/propose-assistant-edits) 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. ## OpenAPI ````yaml api-reference/specs/claudia/v1.json POST /v1/tenants/{tenant}/assistants/propose-create openapi: 3.0.1 info: title: Claudia API version: 1.0.0 servers: - url: https://api.cloudhumans.com/claudia description: Production - url: https://api.cloudhumans.com/claudia/staging description: Staging security: - bearerAuth: [] tags: - name: MCP Servers description: >- The MCP servers your agents can call tools on. Registering one here is what makes its tools selectable in an agent; the credentials it needs are stored encrypted and never read back. - name: Knowledge Base Content description: Read, search and edit the content that answers your customers. - name: Content Quality description: Rewrites proposed for content that is answering your customers badly. - name: Playground description: >- Talk to one of your agents as if you were a customer, without touching a real conversation. - name: Project Settings description: >- Read and change how a ClaudIA project behaves — the settings screens of the ClaudIA app, as an API. - name: Content Improvements description: Answers Claudia proposes for questions your content does not cover yet. - name: Knowledge Bases description: The knowledge bases your account can manage. - name: Content Sources description: The sites Claudia crawls to keep a knowledge base in sync. - name: Agents description: >- The AI agents (assistants) configured for your tenant: the orchestrator (supervisor) and its specialists (react). Reads answer the same passthrough shape the platform stores; creates land as DRAFTS a human reviews and publishes in the app. - name: Agent Tools description: >- The tool catalog your agents can be given, aggregated across every MCP server registered for the tenant. This is the same catalog an assistant's mcp_servers[].tools whitelist is validated against. - name: Conversations description: >- Read access to a conversation's lean investigation summary — messages, status and resolution — and the execution trace behind one of its processed messages, without the internal processing state the hub UI's full read carries. paths: /v1/tenants/{tenant}/assistants/propose-create: post: tags: - Agents summary: Propose a create (preview + confirmation token) description: >- First step of a safe two-step create — nothing is created yet. Send the full create body (for a knowledge-base Q&A agent: `deployment: react`, `graphId: qna_agent`, and `knowledge_base_ids` inside `config`): `config` takes the shape listAssistants and getAssistant return for an existing agent of the same `deployment`, and must carry `project`. `metadata.productionAssistantId` is the ONLY metadata key accepted here — set it to anchor the new draft to a PUBLISHED agent of the same `deployment` on this tenant, which is the pairing proposeAssistantEdits coaches you toward when a published agent has no draft yet; any other metadata key is refused. Returns `message`, `diff`, `preview` and `confirmationId`: `diff` renders the whole state as `+` lines with prompt bodies STUBBED to their real length (`[N chars — use readAssistantText]`) — the full text is exactly what you authored and is what gets created — while `preview` is that same state as it will persist (server defaults and coordinates applied), prompt bodies stubbed the same way. Review the diff, then call confirmAssistantCreate with just that confirmationId; no other body field is read. The agent is ALWAYS created as a DRAFT — a human reviews and publishes it in the ClaudIA app, and this surface has no opt-out. operationId: proposeAssistantCreate parameters: - name: tenant in: path description: >- 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. required: true schema: type: string requestBody: description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ProposeAssistantCreateRequest' required: true responses: '200': description: >- 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. content: application/json: schema: type: object additionalProperties: true '400': description: >- A missing `config.project`, an unknown `deployment`, a blank `name`/`graphId`, or a config the live schema rejects. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, expired or invalid credentials. '403': description: The credentials hold no account allowed to manage this content. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- The tenant, or the project named by `config.project`, is one this token cannot reach — indistinguishable from one that does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- A policy violation (a `metadata` key other than `productionAssistantId`), `metadata.productionAssistantId` does not name a published agent of the same `deployment` on this tenant, or the resolved config references something that does not exist on this tenant: a tool ref, an MCP server id, or a sub-agent. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit applied by the API gateway. Back off and retry. components: schemas: ProposeAssistantCreateRequest: type: object required: - deployment - name - graphId - config properties: deployment: type: string enum: - supervisor - react description: >- 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. name: type: string description: Human-readable agent name. description: type: string description: >- 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. config: type: object additionalProperties: true description: >- 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: type: string description: >- 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. metadata: type: object additionalProperties: true description: >- 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. description: >- The agent to create. `config` must carry `project`. `metadata` accepts only `productionAssistantId`. Error: required: - error type: object properties: error: type: string description: What went wrong. example: 'Forbidden: token holds no claim for the requested account' description: Something the caller needs to fix. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````