## Create site `POST /v1/sites` Creates a new site on your Bitrix24 account. The site type is determined by the `type` field. Fields are passed flat at the root of the JSON — without the `fields` wrapper. ## Request fields (body) | Parameter | Type | Req. | Description | |----------|-----|:-----:|---------| | `title` | string | yes | Site name, up to 255 characters | | `type` | string | no | Site type. Default `PAGE` — landing. Also `STORE` — online store, `KNOWLEDGE` — Knowledge Base 2.0. For `KNOWLEDGE` you must also pass `scope: "KNOWLEDGE"` — see below | | `scope` | string | no | The Bitrix24 section the site is created in: `KNOWLEDGE` (Knowledge Base 2.0), `GROUP` (group knowledge base) or `MAINPAGE`. Without it a regular landing site is created. **To create a knowledge base, pass `scope: "KNOWLEDGE"` together with `type: "KNOWLEDGE"`** — otherwise the server returns `403 BITRIX_ACCESS_DENIED` ("Site creation access denied"). Can be passed as a body field or the `?scope=KNOWLEDGE` query parameter. The same `scope` is needed when [updating](/docs/entities/sites/update) and [deleting](/docs/entities/sites/delete) such a site | | `code` | string | yes | Symbolic site code in the URL. **The key is required**, but the value may be empty (`""`) or `null` — then the code is generated from `title`. If you omit the `code` key itself, creation returns `422` (see "Site address is required" in "Known specifics"). If the code consists only of digits, the `site` prefix is added. If the code is already taken on the domain, a numeric suffix is added (`code2`, `code3`) | | `domainId` | number | no | Domain identifier. If not provided, the address is generated from `code` on `bitrix24site.com` | | `active` | boolean | no | Accepted without error, but not saved. A new site is always created inactive — `active: false`. The site is activated upon publication in the Bitrix24 account interface | | `description` | string | no | Site description, up to 255 characters | | `xmlId` | string | no | External identifier, up to 255 characters | ## Examples ### curl — personal key ```bash curl -X POST "https://vibecode.bitrix24.com/v1/sites" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Conference landing", "code": "conf-2026", "type": "PAGE" }' ``` ### curl — OAuth application ```bash curl -X POST "https://vibecode.bitrix24.com/v1/sites" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Conference landing", "code": "conf-2026", "type": "PAGE" }' ``` ### curl — Knowledge Base 2.0 (`scope=KNOWLEDGE`) ```bash curl -X POST "https://vibecode.bitrix24.com/v1/sites" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Company knowledge base", "type": "KNOWLEDGE", "scope": "KNOWLEDGE" }' ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/sites', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'Conference landing', code: 'conf-2026', type: 'PAGE', }), }) const { success, data } = await res.json() console.log('Site ID:', data.id) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/sites', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'Conference landing', code: 'conf-2026', type: 'PAGE', }), }) const { success, data } = await res.json() ``` ## Response fields The full object of the created site is returned. | Field | Type | Description | |------|-----|---------| | `id` | number | Identifier of the created site | | `title` | string | Site name | | `code` | string | Actual symbolic code (with an auto-suffix if the requested code was taken) | | `type` | string | Site type | | `active` | boolean | Always `false` for a just-created site | | `domainId` | number | Domain identifier (issued automatically or provided) | | `createdById` | number | Identifier of the user who created the site | | `dateCreate` | datetime | Creation date | | `dateModify` | datetime | Last modification date | The site URL in Bitrix24 is built from `id`: ``` https://.bitrix24.com/sites/site// ``` `` is the Bitrix24 account domain. Access is restricted by the employee's permissions in Bitrix24. ## Response example ```json { "success": true, "data": { "id": 173, "title": "Conference landing", "code": "/conf-2026/", "type": "PAGE", "active": false, "domainId": 28, "createdById": 1, "dateCreate": "07.05.2026 12:14:08", "dateModify": "07.05.2026 12:14:08" } } ``` ## Error response example 422 — invalid site code: ```json { "success": false, "error": { "code": "BITRIX_ERROR", "message": "The site address is entered incorrectly. You may use only the following characters: \"a-z\", \"0-9\", \"-\", \".\"." } } ``` ## Errors | HTTP | `error.code` | Marker in `error.message` | Description | |------|--------------|--------------------------|---------| | 422 | `BITRIX_ERROR` | `Required field "Site address" is not filled in` | The `code` key was omitted — the site has no address. Pass `code` with any value, an empty one is allowed | | 422 | `BITRIX_ERROR` | `SLASH_IS_NOT_ALLOWED` | A `/` character was passed in `code` — slashes in the code are not allowed | | 422 | `BITRIX_ERROR` | `DOMAIN_IS_INCORRECT` | The site address is entered incorrectly: only the characters `a-z`, `0-9`, `-`, `.` are allowed | | 422 | `BITRIX_ERROR` | `DOMAIN_EXIST` | The specified domain is already taken by another site | | 422 | `BITRIX_ERROR` | `DOMAIN_EXIST_TRASH` | The domain is bound to a site in the trash — unbind it first | | 422 | `BITRIX_ERROR` | `DOMAIN_NOT_FOUND` | A domain with the specified `domainId` does not exist | | 422 | `BITRIX_ERROR` | `SITE_LIMIT_REACHED` | The site count limit on the current plan has been reached | | 403 | `BITRIX_ACCESS_DENIED` | `Site creation access denied` | The user does not have permission to create sites — OR `type: "KNOWLEDGE"` is being created without `scope: "KNOWLEDGE"` (add `scope`, see the fields table) | | 403 | `SCOPE_DENIED` | — | The API key does not have the `landing` scope | | 401 | `TOKEN_MISSING` | — | The API key has no configured tokens | The full list of common API errors — [Errors](/docs/errors). ## Known specifics **Slashes in the response.** The `code` field in the response is returned with framing slashes (`/conf-2026/`) — this is the representation of the site path in the URL. Slashes cannot be passed in the request. **The `code` key is required.** The `code` value may be an empty string `""` or `null` — then the code is generated from `title`. But if you omit the `code` key itself, creation returns `422 BITRIX_ERROR` with the message `Required field "Site address" is not filled in`. If `domainId` is not provided, the address is generated from `code` on `bitrix24site.com`, for example `b24-xxxxx.bitrix24site.com`. **Home page and error pages.** The `landingIdIndex`, `landingId404`, `landingId503` fields are not set on create — there are no pages yet. Assign them via [update](/docs/entities/sites/update) after the site pages are created. **Knowledge Base 2.0.** Created as a site with `type: "KNOWLEDGE"` AND `scope: "KNOWLEDGE"` — both fields are required. Without `scope` the server returns `403 BITRIX_ACCESS_DENIED`, because Bitrix24 creates `KNOWLEDGE`-type sites only in the knowledge-base section (the same `scope` is available for list, get, update and delete — see the respective methods). The key's `landing` scope is sufficient. No separate knowledge-base scope is required. ## See also - [List sites](/docs/entities/sites/list) — view existing sites before creating - [Update site](/docs/entities/sites/update) — change the parameters of a created site - [Delete site](/docs/entities/sites/delete) — delete an empty site - [Batch](/docs/batch) — bulk creation - [Limits and optimization](/docs/optimization) — rate limits