# 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 account-bound key (personal or OAuth application) ·
**Base URL:** `https://vibecode.bitrix24.com/v1` · **Authorization:** `X-Api-Key` header

## 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. Copies the AI prompt — it contains the app name and a link of the form
   `GET /v1/app/blueprints/:slug` (with a `locale` parameter), tagged with the user's 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.

## 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

| Parameter | Type | Req. | Description |
|----------|-----|:-----:|---------|
| `slug` (path) | string | yes | Blueprint identifier from the link in the copied prompt |
| `locale` (query) | `ru` \| `en` | no | Spec body language. Any value other than exactly `ru` (including an omitted parameter) returns `en` |

## 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-fetch statistics from these requests).

## Response example

Body excerpt for `slug=tasks-report`:

```markdown
# Task report

## What the app does
An embeddable Bitrix24 reporting app for a team lead. Answers three questions on one screen: which
tasks are already overdue, what each assignee is working on, and how the status picture changed over
the week.

## Screens and features
- Top KPI row: total active tasks, overdue, completed this week, average time to close.
- "Assignee × active × overdue × completed" table, sorted by overdue count.
```

## 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 |
| 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 recognizes only the exact value `ru` — any other value (including typos like
  `RU`, or an omitted parameter) silently returns the English spec.
- The blueprint list and its `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: it talks to Bitrix24 through one
  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 & Auth](/docs/keys-auth)
- [Deploy API](/docs/infra/deploy)
- [API changelog](/docs/changelog)