# 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](/docs/keys-auth/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`

`HEAD` is not supported at this address and returns `404`. Use `GET` to retrieve the spec.

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

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `slug` (path) | string | yes | Blueprint identifier from the link in the copied prompt |
| `locale` (query) | string | no | Spec body language. Defaults to `en`; an unrecognized value also returns the English spec |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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

```javascript
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

```javascript
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`:

```markdown
# 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`:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 404 | `BLUEPRINT_NOT_FOUND` | Unknown or hidden `slug` |
| 403 | `BLUEPRINTS_DISABLED` | The "App blueprints" section is not enabled for the key's portal — see [Blueprint availability](#blueprint-availability) |
| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | A management key is not bound to a portal — use a personal key or an OAuth application key |

Full list of common API errors — [Errors](/docs/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](/docs/keys-auth)
- [Deploy API](/docs/infra/deploy)
- [API changelog](/docs/changelog)