## Create a page `POST /v1/pages` Creates a new page on the specified site. Fields are passed flat at the root of the JSON — without a `fields` wrapper. The minimum required fields are `title` and `siteId`. A new page is created inactive — `active: false`. ## Request fields (body) | Field | Type | Required | Description | |------|-----|:-----:|---------| | `title` | string | yes | Page title, up to 255 characters | | `siteId` | number | yes | Site identifier. Source: [`GET /v1/sites`](/docs/entities/sites/list) | | `code` | string | no | Symbolic code of the page in the URL. Must not contain `/`. If the field is omitted, the code is generated from `title`. An empty string returns `422 BITRIX_ERROR`, except when creating a folder with `folder: "Y"`: then the code is also generated from `title`. If the code is already taken on the site, a numeric suffix is added | | `description` | string | no | Arbitrary page description | | `public` | string | no | Public flag (`Y`/`N`) | | `sitemap` | string | no | Include in the sitemap (`Y`/`N`) | | `xmlId` | string | no | External code | | `folderId` | number | no | ID of the site's section folder | | `tplId` | number | no | Template ID | > For the full list of fields, see [`GET /v1/pages/fields`](./fields.md): the endpoint returns a map of all fields with their type, a `readonly` flag and a label. Fields without a `readonly` flag are writable. The additional fields listed above are applied on creation alongside `title`/`siteId`/`code`/`description`. **Publishing is a separate call.** The `active` field is not accepted in the create body: a request carrying it is rejected as a whole with `400 READONLY_FIELD` and no page is created. To publish a created page, call `POST /v1/pages/:id/publication`; to unpublish it, call `POST /v1/pages/:id/unpublish`. ## Examples ### curl — personal key ```bash curl -X POST "https://vibecode.bitrix24.com/v1/pages" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Spring sale", "code": "spring-sale", "siteId": 3, "description": "Landing page for a seasonal sale" }' ``` ### curl — OAuth application ```bash curl -X POST "https://vibecode.bitrix24.com/v1/pages" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Spring sale", "code": "spring-sale", "siteId": 3, "description": "Landing page for a seasonal sale" }' ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/pages', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'Spring sale', code: 'spring-sale', siteId: 3, description: 'Landing page for a seasonal sale', }), }) const { success, data } = await res.json() console.log('Page ID:', data.id) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/pages', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'Spring sale', code: 'spring-sale', siteId: 3, description: 'Landing page for a seasonal sale', }), }) const { success, data } = await res.json() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | The created page | | `data.id` | number | Identifier of the created page | | `data.title` | string | Page title | | `data.code` | string | Actual symbolic code. If the requested code was taken, it carries a numeric suffix | | `data.siteId` | number | Site identifier | | `data.active` | boolean | Always `false` for a just-created page | | `data.description` | string \| null | Page description | | `data.createdById` | number | Identifier of the employee who created it | | `data.dateCreate` | datetime | Creation date. A string in the account locale format, not ISO 8601 | | `data.dateModify` | datetime | Last modification date | The main fields are shown. Full list: [Field reference](/docs/entities/pages/fields). > **Date format.** `dateCreate` and `dateModify` are strings in the account locale format, **not** ISO 8601 (`30.12.2021 12:30:52` in the RU locale, `12/30/2021 12:30:52 pm` in the EN locale). The format is the same in the list and in the card; do not rely on `new Date()` to parse such a value. Details: [Field reference](/docs/entities/pages/fields). The page URL in Bitrix24 is built from `id` and `siteId`: ``` https://.bitrix24.com/sites/site//view// ``` `` — ID of the site the page belongs to (the `siteId` field in the response). `` — the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24. ## Response example ```json { "success": true, "data": { "id": 2295, "title": "Spring sale", "code": "spring-sale", "siteId": 3, "active": false, "description": "Landing page for a seasonal sale", "createdById": 1, "dateCreate": "08.05.2026 11:49:33", "dateModify": "08.05.2026 11:49:33" } } ``` ## Error response example 422 — the required `title` field was not passed: ```json { "success": false, "error": { "code": "BITRIX_ERROR", "message": "Required field \"Page title\" is not filled in" } } ``` ## Errors | HTTP | `error.code` | Marker in `error.message` | Description | |------|--------------|--------------------------|---------| | 400 | `READONLY_FIELD` | — | A read-only field was passed in the body — for example `active`. The page is not created | | 422 | `BITRIX_ERROR` | `is not filled in` | `title` or `siteId` is missing | | 422 | `BITRIX_ERROR` | `Slash is forbidden in the landing address` | A `/` character was passed in `code` — slashes are forbidden in the code | | 422 | `BITRIX_ERROR` | `Page address cannot be empty` | An empty string was passed in `code` without indicating that a folder is being created | | 422 | `BITRIX_ERROR` | `Invalid page address` | A value in the `__` format was passed in `code`, e.g. `code_12_34` | | 404 | `ENTITY_NOT_FOUND` | `Site not found` | A nonexistent site identifier was passed in `siteId` | | 403 | `BITRIX_ACCESS_DENIED` | — | The user does not have the "edit" permission for the specified site | | 403 | `SCOPE_DENIED` | — | The API key does not have the `landing` scope | | 401 | `TOKEN_MISSING` | — | The API key has no configured tokens | Full list of general API errors — [Errors](/docs/errors). ## See also - [List pages](/docs/entities/pages/list) - [Get a page](/docs/entities/pages/get) - [Update a page](/docs/entities/pages/update) - [Delete a page](/docs/entities/pages/delete) - [Sites](/docs/entities/sites) - [Batch](/docs/batch) - [Limits and optimization](/docs/optimization)