App blueprints

A library of ready-made technical specs for popular Bitrix24 apps — dashboards, AI bots, calculators. The user picks a blueprint in the Vibecode dashboard and copies a prompt for their AI agent. The prompt carries a link to the raw spec markdown at this endpoint — the agent downloads the spec with the same API key and builds the app from it. The section has one endpoint — fetching a blueprint's spec.

Scope: none required — works with any key bound to a Bitrix24 account (personal or OAuth application) · Base URL: https://vibecode.bitrix24.com/v1 · Authorization: X-Api-Key header

Blueprint availability

Blueprints are opened to Bitrix24 accounts in turn, and the Vibecode team turns them on — there is no such setting on the account side. The signs that the section is not open yet: the Vibecode dashboard has no "App blueprints" item, and a spec request answers 403 with the BLUEPRINTS_DISABLED code. To have the section opened, contact support.

How it works

1. The user opens the "App blueprints" section in the Vibecode dashboard (/blueprints) or picks a blueprint in the key-creation dialog.
2. The user copies the AI prompt — it contains the app name and a link of the form GET /v1/app/blueprints/:slug (with a locale parameter), to be fetched with the user's own key.
3. The AI agent (Claude Code, Cursor, and similar) makes the request with its own API key and receives the raw spec markdown — then builds the app from that text.

The list of available slug values isn't published as a separate V1 endpoint — the agent only needs the link from the copied prompt. There's no need to look up a slug in advance.

Design for a new app

Before choosing the design, the agent reads the full successful response from GET /v1/me with the app's key and applies data.uiDesign with policyVersion=2. With MCP, use a full get_me({}) read without sections, where the block is named uiDesign. A blueprint points to this source instead of carrying its own rule table or palette.

A standard request for a new app without a named target and with a confirmed portal_bound binding selects light Bitrix24 design for the first version without asking about the target or brand. This is a design default, not a choice of iframe or placement architecture. An explicitly external page requires a question about the brand and how to apply it, and explicit design preferences take priority. With unresolved, including a management key, select a Bitrix24 account and read the response with its APP key or clarify the target. The binding provides design context but neither proves an iframe nor grants creation, embedding or publication rights.

If the request fails, the block is absent or the policy version is unsupported, the agent reports that the rule could not be read and clarifies the design. Existing UI keeps its design. Background processes, bot messages and generated documents do not inherit page styling: a settings screen or operator panel is considered separately as UI.

For new B24 UI, include CSS once and pin the exact version URL from css.href behind the gateway or css.publicHref on your own hosting. Updates to the shared set do not restyle an existing app. The UI root must use font-family: var(--ui-font-family-primary, var(--ui-font-family-system)) without loading a network font. Select only the official b24icons needed for the actions, from a pinned release: Vue uses individual @bitrix24/b24icons-vue/<group>/<Icon> imports, while other stacks use verified local SVG files. Record the version, origin, MIT license and checksums with the app. Do not load the full catalog or a runtime CDN, or allow external links or scripts in SVG files. An unavailable CSS version or an unsafe icon requires reporting the incompatibility instead of substituting a resource.

Get a blueprint spec

GET /v1/app/blueprints/:slug

Returns the raw spec markdown. The response is not a JSON envelope — the response body is the spec text as-is, with Content-Type: text/markdown; charset=utf-8.

Parameters

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/app/blueprints/tasks-report?locale=en" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/app/blueprints/tasks-report?locale=en" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/app/blueprints/tasks-report?locale=en', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const specMarkdown = await res.text()

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/app/blueprints/tasks-report?locale=en', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const specMarkdown = await res.text()

Response

On success — HTTP 200 with a text/markdown; charset=utf-8 body (not JSON) and a Cache-Control: no-store header (the response is deliberately not cached — the platform counts blueprint fetches from these requests).

Response example

Body excerpt for slug=tasks-report:

# Tasks report

Before choosing the design or asking about where the app will be used or its brand, read the full
successful JSON response from `GET /v1/me` using the app's key and apply `data.uiDesign` as the source
of the design rule for the new UI. If the request fails or the block is missing or unsupported,
report that the rule could not be read and clarify the design.

## What the app does
An embeddable Bitrix24 report for a team lead. It answers three questions on one screen: which tasks
are already overdue, what each assignee is busy with, and how the status picture shifted over the week.
Data comes from Bitrix24 Tasks in real time, with no manual exports: open the widget and see where the
bottleneck is and who to hand work to. It lets a lead run the stand-up on numbers instead of gut feel
and never miss a task whose deadline is burning.

Error response example

404 — unknown or hidden slug:

{
  "success": false,
  "error": { "code": "BLUEPRINT_NOT_FOUND", "message": "Blueprint not found" }
}

Errors

Full list of common API errors — Errors.

Known specifics

• The response is not JSON. Read the body as text (res.text()), not res.json().
• The locale parameter defaults to en. A misspelled or unsupported value silently returns the English spec instead of an error.
• The blueprint list and the slug values have no dedicated V1 endpoint — the "App blueprints" section and the key-creation dialog in the dashboard already substitute the correct link into the copied prompt.
• Spec bodies do not promise role-based access inside the app: the app talks to Bitrix24 through a single webhook key belonging to its owner, with the owner's rights. If the app is shared with another employee, they see exactly what the key owner sees.

See also

• Keys and authorization
• Deploy API
• API changelog