## Create site

`POST /v1/sites`

Creates a new site in 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 | Required | Description |
|----------|-----|:-----:|---------|
| `title` | string | yes | Site name, up to 255 characters |
| `type` | string | no | Site type. Default `PAGE` — landing page. 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 "The `code` key 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` |
| `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",
    "code": "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 |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | The created site. All fields — [Site fields](/docs/entities/sites/fields) |
| `data.id` | number | Identifier of the created site |
| `data.title` | string | Site name |
| `data.code` | string | Actual symbolic code (with an auto-suffix if the requested code was taken) |
| `data.type` | string | Site type |
| `data.active` | boolean | Always `false` for a just-created site |
| `data.domainId` | number | Domain identifier (issued automatically or provided) |
| `data.createdById` | number | Identifier of the user who created the site. Lookup: `GET /v1/users` |
| `data.dateCreate` | datetime | Creation date |
| `data.dateModify` | datetime | Last modification date |

The site URL in Bitrix24 is built from `id`:

```
https://<portal>.bitrix24.com/sites/site/<id>/
```

`<portal>` is the Bitrix24 portal 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 |
|------|--------------|--------------------------|---------|
| 400 | `READONLY_FIELD` | `Field 'active' is read-only` | The body carried `active` — the field is read-only (Bitrix24 does not store it). Drop it from the body; a site is activated by `POST /v1/sites/:id/publication` or by publishing it in the interface |
| 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, even an empty one |
| 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 a `type: "KNOWLEDGE"` site 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 leading and trailing 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`.

**The active flag cannot be set through the API.** The `active` field is read-only: Bitrix24 does not store the passed value on create or on update, so a request carrying it is refused with `400 READONLY_FIELD` before the Bitrix24 call. A new site is always created inactive — `active: false` in the response; a site is activated by [`POST /v1/sites/:id/publication`](/docs/entities/sites/publication) or by publishing it in the Bitrix24 account interface.

**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)
- [Update site](/docs/entities/sites/update)
- [Delete site](/docs/entities/sites/delete)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)