# Create Bot

> Create a bot desired-state record and enqueue reconcile notification.

Canonical URL: https://docs.botyard.io/docs/api/bots/create_bot_v1_orgs__org_id__bots_post

`POST /v1/orgs/{org_id}/bots`

Create a bot desired-state record and enqueue reconcile notification.

Per-bot resource overrides are available on every plan; the plan's
``resource_maximums`` still bound how high each dimension may go.

Optional ``credentials`` and ``tool_domain_settings`` are applied in the
same transaction, before the bot is first provisioned, under the same rules
as ``PUT …/credentials`` and ``PUT …/tool-domain-settings/{domain}``; any
invalid entry fails the whole create. Sending settings without
``bot:tool_domain_settings.update`` is a 403.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | yes | string |  |

## Request body

`application/json`: BotCreate (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Bot display name |
| `avatar_url` | string \| null | no | Avatar image URL — an image data URI (DiceBear SVG, or an uploaded WebP/PNG/JPEG) or an https:// URL. Max 16384 characters. |
| `description` | string \| null | no | Short human-facing description / role for the bot (e.g. 'Platform developer'). Display metadata only — not injected into the bot's system prompt. |
| `tier` | BotTier | no | Bot tier |
| `hosting_type` | BotHostingType | no | Who runs this bot's runtime. Immutable after creation. Must form a permitted pair with `harness` — see `GET /orgs/{org_id}/bots/hosting-options`. |
| `harness` | BotHarness | no | Which agent software this bot runs. Immutable after creation. Must form a permitted pair with `hosting_type` — see `GET /orgs/{org_id}/bots/hosting-options`. |
| `config` | OpenClawConfigPatch \| NativeConfigPatch | yes | Initial bot config (applied on top of defaults) |
| `guided_setup` | boolean | no | When true, the bot starts in guided-setup mode: it introduces its capabilities and configures itself by chatting with the user. The guided-setup template bundle is unioned with skill_ids/tool_ids. |
| `skill_ids` | array of string | no | Skills to assign at creation (the wizard's final selection). |
| `tool_ids` | array of string | no | Tools to assign at creation (the wizard's final selection). |
| `files` | object | no | Initial workspace files keyed by file type (soul, heartbeat, agents, tools). Deployed by the reconciler on first provision. |
| `resources` | ResourceQuantities \| null | no | Per-bot resource customisation on top of the plan preset — a sparse list of MeteredResource line-items (only the resources being set; omitted resources use the preset). Available on every plan, subject to the plan's resource maximums. |
| `credentials` | BotCredentialAssign \| null | no | Credential assignments to apply atomically with creation — the same body, validation, and bot-owner gate as `PUT /orgs/{org_id}/bots/{bot_slug}/credentials`. Model routing is derived from these links before the bot is first provisioned, so it boots on the chosen model instead of being reconfigured (and restarted) moments later. Any invalid assignment fails the whole create. Only credentials that already exist can be linked; a bot-private credential needs the bot first and is still assigned after creation. |
| `tool_domain_settings` | object | no | Per-tool-domain settings to apply atomically with creation, keyed by domain (e.g. `sessions`) — the same validation and `bot:tool_domain_settings.update` permission as `PUT /orgs/{org_id}/bots/{bot_slug}/tool-domain-settings/{domain}`. Each value's `tool` discriminator must match its key. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | Successful Response | BotResponse |
| `422` | The edit would leave a native bot with an LLM credential owned mode does not serve (native_lane_refused), or the request failed validation | NativeLaneRefusedProblem \| ProblemDetails, NativeLaneRefusedProblem |
| `default` | RFC 9457 Problem Details error response | ProblemDetails |

Full schemas: operation `create_bot_v1_orgs__org_id__bots_post` in the OpenAPI spec at https://api.botyard.io/openapi.json.