---
name: rombik-api
description: Генерує блок-схеми алгоритмів за ДСТУ з вихідного коду (Python, C++, C, Java, C#, Pascal) через HTTP API rombik. Використовуй, коли треба перетворити код на блок-схему у форматах docx/typst/excalidraw/svg/png/pdf.
---

# rombik API — скіл для агентів

rombik перетворює вихідний код на блок-схему алгоритму за ДСТУ 19.701-90 по HTTP.
Авторизація — API-ключем. 1 схема — 1 кредит.

## База
`https://rombik.app/api/v1` — напр. ендпоінт /render це https://rombik.app/api/v1/render

## Авторизація
Заголовок (будь-який із двох):
- `X-API-Key: rk_...`
- `Authorization: Bearer rk_...`

Ключ створюється у кабінеті користувача на сайті (показується один раз).

## CLI (рекомендовано для агентів)
Замість сирих HTTP-викликів із ключем у промпті — постав CLI `rombik`, він тримає ключ у конфігу (`~/.config/rombik`), тож ключ НЕ потрапляє в контекст моделі:
```bash
curl -fsSL https://rombik.app/install.sh | sh   # macOS/Linux → ~/.local/bin
# Windows (PowerShell): irm https://rombik.app/install.ps1 | iex
rombik auth                                # вхід через браузер (або: rombik auth rk_…)
```
Далі працюй командами, НЕ передаючи ключ аргументом (він береться з конфігу):
- `rombik render main.py -f pdf -o out.pdf` — файл/stdin/`--url` → схема
- `rombik batch src/*.py -f pdf -o project.pdf` — багато джерел за раз
- `rombik me` · `rombik products` · `rombik topup` · `rombik gift --email … --qty …`
- `rombik version --json` → `{version,latest,updateAvailable}`; `rombik update` — оновити CLI до найновішої версії
- Опції рушія — ті самі прапорці, що й поле `options` в API: `--locale`, `--for-format`, `--single-end`, `--strip-types`, `--yes/--no`, `--in-word/--out-word`, `--cap-word/--cap-format` тощо (повний перелік: `rombik render -h`; кастомні — лише з Pro).
Команди 1:1 з HTTP-ендпоінтами нижче; коди виходу — за `code` помилки. Завантаження й деталі: https://rombik.app/developers

## MCP (для клієнтів без shell)
Якщо ти працюєш у клієнті з підтримкою MCP (Claude Desktop, Cursor, Cline…), той самий бінар уміє бути MCP-сервером — тоді не треба запускати команди в shell, інструменти доступні нативно. Користувач один раз ставить CLI, робить `rombik auth` і додає в конфіг MCP-клієнта:
```json
{ "mcpServers": { "rombik": { "command": "rombik", "args": ["mcp"] } } }
```
Інструменти: `render_flowchart` (code|url → PNG картинкою, або svg/typst/excalidraw/pdf), `balance`, `products`, `topup_link`, `gift_credits`. Транспорт — stdio; помилки API з `code` повертаються як isError.

## Ендпоінти

### POST /render — код → схема (1 схема — 1 кредит)
Тіло JSON: `{ "code": "...", "lang": "python", "format": "svg" }`
- `lang`: python | cpp | c | java | csharp | pascal
- `format`: docx | typst | excalidraw | svg | png | pdf | json (типово svg). `docx` — Word із нативними фігурами; `json` — сира геометрія Diagram.
- `split` (дефолт true для docx, PDF і Typst-документа; для svg/png/excalidraw — за явним true): різати високі схеми на частини конекторами А/Б. У docx/pdf/typst це окремі сторінки (pdf — багатосторінковий), у svg/png/excalidraw — частини в одному полотні. `false` — лишити суцільною (один аркуш)
- `url`: замість `code` — посилання на файл (allowlist: raw.githubusercontent.com, gist, gitlab.com, bitbucket.org, codeberg.org; `github.com/.../blob/...` авто→raw). Мова вгадується за розширенням.
- опційно: `fn` (лише функція з цим іменем), `scale` (zoom для PNG), `fragment` (Typst-фрагмент), `font`, `options` (обʼєкт — повний перелік у розділі «Опції рушія» нижче)
- `options` із кастомними словами/підписом/форматом for — лише для акаунтів з активним **Pro** (інакше 402 `pro_required`). Тумблери, `locale`, `font`, `scale`, `figStart` — безкоштовні.
- `?json=1` → відповідь JSON `{ format, encoding (utf-8|base64), content, creditsLeft }` замість файлу

### POST /render/batch — багато джерел за раз (1 кредит/елемент)
Тіло: `{ "items": [ {"code":"...","lang":"python"}, {"url":"https://raw.../b.cpp"} ], "format": "pdf" }`
- `items`: 1..100 елементів, кожен `{ code|url, lang?, fn?, name? }`.
- Списує 1 кредит за КОЖНУ схему серед успішних елементів; на балансі — щонайменше за кількістю елементів.
- `format=pdf` (і не `bundle:"zip"`) → один багатосторінковий PDF (сторінка на елемент); інші формати → zip із файлом на елемент.
- `?json=1` → звіт `{ count, rendered, creditsLeft, items:[{index,name,ok,error}], encoding:base64, content }`; інакше файл (pdf|zip) + заголовки `X-Rombik-Rendered`, `X-Rombik-Failed`.

Приклад (JSON):
```bash
curl -X POST https://rombik.app/api/v1/render \
  -H "X-API-Key: rk_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"code":"def f(a):\n    return a*2","lang":"python","format":"svg"}' -o out.svg
```
Приклад (файл): `curl -X POST https://rombik.app/api/v1/render -H "X-API-Key: rk_..." -F file=@prog.py -F format=pdf -o out.pdf`

### Рідний формат rombik (lang=`rombik`) — пряма структура схеми (Pro)
Коли rombik НЕ парсить мову (асемблер, псевдокод, JS…) або схема не відповідає жодному
коду — постав `lang:"rombik"` і поклади в `code` ДЕРЕВО схеми як astJSON (рядок JSON).
Парсер пропускається. Лише **Pro** (інакше 402 `pro_required`). Формати й `options` — як звичайно.

**Модель.** Ти описуєш лише ЛОГІКУ (послідовність дій, розгалуження, цикли) і ТЕКСТ
вузлів. ДСТУ-обрамлення layout додає САМ: овали Початок/Кінець навколо функції, мітки
Так/Ні на ромбах, самі форми, нумерацію «Рисунок N». Їх вручну НЕ пиши.

**Верхній рівень:** `code` = JSON-МАСИВ функцій (кожна = окрема схема):
```json
[ { "name": "ім'я", "main": true, "block": { "kind": "block", "stmts": [ ...вузли... ] } } ]
```
`stmts` — послідовність вузлів зверху вниз. `main:true` — головна функція.

**Вузол:** `{ "kind": …, "text"?, "cond"?, "then"?, "else"?, "body"?, "stmts"?, "jump"? }`. Види:

| kind | форма | поля |
|------|-------|------|
| process | прямокутник | text |
| io | паралелограм | text (почни з «Ввід»/«Вивід») |
| call | підпрограма | text (виклик функції) |
| terminal | овал | text (return/raise) |
| if | ромб | cond + then + else |
| for | шестикутник | cond (специфікація!) + body |
| while | ромб (передумова) | cond + body |
| dowhile | ромб (постумова) | cond + body |
| infloop | цикл | body |
| break / continue | — | лише в циклі |
| connector | коло | text; jump:true — goto |

⚠️ **Ключове:**
- `then`/`else`/`body` — це БЛОК-вузли виду `{ "stmts": [ … ] }`; порожня гілка = `{ "stmts": [] }`.
- У `for` специфікація йде в полі `cond` (НЕ в `text`!), формат «змінна := старт, кінець[, крок]», напр. `i := 1, n`.
- НЕ додавай вузли Початок/Кінець і НЕ пиши Так/Ні — це робить layout.

**Рецепти (конструкція → astJSON).** if / elif / else (elif = вкладений if усередині else):
```json
{ "kind": "if", "cond": "x > 0",
  "then": { "stmts": [ { "kind": "io", "text": "Вивід: плюс" } ] },
  "else": { "stmts": [
    { "kind": "if", "cond": "x < 0",
      "then": { "stmts": [ { "kind": "io", "text": "Вивід: мінус" } ] },
      "else": { "stmts": [ { "kind": "io", "text": "Вивід: нуль" } ] } } ] } }
```
Цикл for (діапазон) і while:
```json
{ "kind": "for", "cond": "i := 0, n-1",
  "body": { "stmts": [ { "kind": "call", "text": "обробити(i)" } ] } }

{ "kind": "while", "cond": "b <> 0",
  "body": { "stmts": [ { "kind": "process", "text": "t := b" } ] } }
```

**Повний приклад — пошук максимуму в масиві:**
```json
[
  { "name": "findMax", "main": true, "block": { "kind": "block", "stmts": [
    { "kind": "io", "text": "Ввід a, n" },
    { "kind": "process", "text": "m := a[0]" },
    { "kind": "for", "cond": "i := 1, n-1", "body": { "stmts": [
      { "kind": "if", "cond": "a[i] > m",
        "then": { "stmts": [ { "kind": "process", "text": "m := a[i]" } ] },
        "else": { "stmts": [] } }
    ] } },
    { "kind": "io", "text": "Вивід m" },
    { "kind": "terminal", "text": "Повернути m" }
  ] } }
]
```

**Помилки валідації** (повертаються текстом — виправ і повтори): невідомий kind; if/while/for
без cond; process/io/call без text; break/continue поза циклом; ліміти (≤2000 вузлів, глибина ≤100).

**Виклик:** `rombik render schema.json --lang rombik -f pdf -o out.pdf`, або MCP `render_flowchart` з `lang:"rombik"`, або POST /render. Потрібен Pro.

### GET /me — баланс
→ `{ email, name, credits, pro, proUntil }`

### POST /topup — лінк на оплату (коли скінчились кредити)
- `{ "kind": "credits_unit", "qty": 10 }` — поштучно
- `{ "kind": "credits", "id": <packId> }` — пакет (id з /products)
- `{ "kind": "pro", "id": <tierId> }` — Pro
→ `{ jarUrl, comment, label, amountKop, amountUah }`. Відкрий `jarUrl`, оплати; кредити зарахуються за ~хвилину (опитуй GET /me).

### GET /products — каталог цін
→ `{ credits:[{id,qty,uah}], pro:[{id,bonus,days,uah}], unitUah, available }` (`available:false` → оплата тимчасово недоступна)

### POST /gift — подарувати кредити другові за email
- `{ "email": "friend@example.com", "qty": 5 }` — списує 5 кредитів у тебе, нараховує другові.
- Якщо акаунта отримувача ще нема — він створюється за email (кредити чекатимуть на вході). Отримувач отримає лист і сповіщення.
→ `{ ok, credits }` (твій новий баланс). Помилки: `gift_failed` (400, напр. недостатньо кредитів), `bad_email`, `bad_qty`.

## Опції рушія — обʼєкт `options` у /render і /render/batch
Потужне налаштування схеми під вимоги (викладача/стандарту). Використовуй сміливо.
Тумблери, `locale`, `font`, `scale`, `figStart` — безкоштовні; кастомні текстові
значення (свої слова) — лише з активним Pro на акаунті (інакше 402 `pro_required`).
```
# тумблери (true/false, дефолт false):
singleEnd            один спільний «Кінець» замість окремого на кожен вихід
mainOnlyTerminators  Початок/Кінець лише для main; підпрограми → Вхід/Вихід
callAsProcess        виклик функції як «Процес», а не «Підпрограма»
stripTypes           прибрати анотації типів з блоків
returnAsIO           return як блок виводу
# текстові / числові:
locale                "uk" | "en" — мова службових вставок схеми
forFormat             "comma" | "range" | "verbose" — вигляд лічильникового for
yes / no              підписи гілок (Так/Ні · Yes/No · +/−)
inWord / outWord      слова вводу/виводу (Ввід/Вивід)
startText / endText   термінатори main (Початок/Кінець)
entryText / exitText  термінатори підпрограм (Вхід/Вихід)
returnWord            слово перед return (Повернути)
forEachWord           роздільник foreach (∈)
capWord               слово підпису (Рисунок)
capFormat             шаблон підпису: {word} {num} — {text}
figStart              з якого номера нумерувати схеми (ціле)
```
Приклад: {"code":"…","lang":"python","options":{"locale":"en","yes":"True","no":"False","singleEnd":true,"stripTypes":true}}
У CLI ці опції — прапорці: --locale, --for-format, --single-end, --yes/--no, --strip-types … (повний перелік: rombik render -h).

## Помилки
Тіло `{ error, code }`. Гілкуйся по `code` (стабільний), не по тексту:
- `unauthorized` (401) — поганий/відсутній ключ
- `no_credits` (402) — немає кредитів → зроби /topup
- `pro_required` (402) — кастомні Pro-опції без активного Pro; поле `proFeatures` перелічує які
- `unknown_format` / `unknown_lang` / `bad_request` (400)
- `bad_source` (400) — не вдалося завантажити `url` (хост не дозволено, недоступний, завеликий)
- `render_failed` (500) — код розпарсився, але рендер/растеризація впали (перевір синтаксис, мову, fn)
- `rate_limited` (429) — лише безкоштовні ендпоінти; є заголовок Retry-After
- `payment_unavailable` (503), `server_error` (500)

## Кредити й ліміти
- 1 схема — 1 кредит; безкоштовного рівня в API немає.
- /render — без ліміту (обмежений кредитами). /me, /topup, /products, /gift — 60 запитів/хв на ключ.

## Машиночитана специфікація
OpenAPI 3.1: https://rombik.app/api/v1/openapi.json