For AI agents: markdown of this page — /docs-content-en/entities/sites/ai/generate.md documentation index — /llms.txt

Start a site generation

POST /v1/sites/ai/generate

Starts site generation from a text brief.

Request body

Field Type Required Description
Fielddescription Typestring Requiredyes DescriptionSite brief, at most 4000 characters; validated by Bitrix24

Parameters

Parameter Type Required Default Description
ParameterIdempotency-Key (header) Typestring Requiredno Defaultabsent DescriptionNon-empty client key forwarded unchanged; empty or whitespace-only values are treated as absent

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/sites/ai/generate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-site-generation-1" \
  -d '{"description": "A small demonstration website for a flower shop. This is an API integration test."}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/sites/ai/generate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-site-generation-1" \
  -d '{"description": "A small demonstration website for a flower shop. This is an API integration test."}'

JavaScript — personal key

javascript 
const res = await fetch("https://vibecode.bitrix24.com/v1/sites/ai/generate", {
  "method": "POST",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "example-site-generation-1"
  },
  "body": JSON.stringify({"description": "A small demonstration website for a flower shop. This is an API integration test."})
});
const result = await res.json();
console.log(result);

JavaScript — OAuth application

javascript 
const res = await fetch("https://vibecode.bitrix24.com/v1/sites/ai/generate", {
  "method": "POST",
  "headers": {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "example-site-generation-1"
  },
  "body": JSON.stringify({"description": "A small demonstration website for a flower shop. This is an API integration test."})
});
const result = await res.json();
console.log(result);

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionGeneration state
Fielddata.id Typenumber DescriptionGeneration identifier
Fielddata.status Typestring Descriptionrunning, completed or failed
Fielddata.siteId Typenumber DescriptionGenerated site identifier, 0 until created; sites
Fielddata.pageId Typenumber DescriptionGenerated page identifier, 0 until created; pages
Fielddata.draftSiteId Typenumber DescriptionDraft site identifier on failure, 0 otherwise
Fielddata.draftPageId Typenumber DescriptionDraft page identifier on failure, 0 otherwise
Fielddata.message Typestring DescriptionHuman-readable state; use status for branching
Fielddata.error Typestring | null DescriptionFailure reason or null
Fielddata.errorDetails Typestring | null DescriptionRequest-limit detail or null

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 11,
    "status": "running",
    "siteId": 0,
    "pageId": 0,
    "draftSiteId": 0,
    "draftPageId": 0,
    "message": "Generating a site",
    "error": null,
    "errorDetails": null
  }
}

Error response example

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request validation failed"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 refused the request
HTTP401 CodeMISSING_API_KEY, INVALID_API_KEY, TOKEN_MISSING DescriptionMissing or unusable credentials
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the landing scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key forbids writes

Common errors.

Known specifics

Bitrix24 automatically attempts to publish the generated site. Include only information intended for public viewing in the description.

The generation takes the user's available AI site draft. An open AI site chat loses it and must be reloaded. Send a client Idempotency-Key to reuse the completed response for 24 hours. Concurrent repeats before that response is stored are not protected. Without the header, or with an empty or whitespace-only header, every call starts another generation. The platform does not retry the start automatically.

Calls run as the webhook owner or the user whose OAuth token the key uses. Read the result through generation status: running, completed or failed.

See also