CRM API — Довідник ендпоінтів

Arc OS — The Orchestration System for AI Teams

Загальна інформація

Автентифікація

Всі ендпоінти (окрім /docs/*) вимагають JWT токен у заголовку Authorization: Bearer <token>.

Для SSE та WebSocket з'єднань токен передається через query-параметр ?token=<JWT>.

Помилки авторизації

Ендпоінти за категоріями

Акаунт та налаштування

Онбординг + Trial Credits (Phase 50.1)

Beta Invites (Phase 52.1, admin-only)

Auth flow update: POST /api/auth/register тепер вимагає поле invite_code (Phase 52.1 closed beta). Без коду → 403 {error: "invite_required"}. Невалідний/used код → 403 {error: "invalid_invite"}.

Billing (Phase 51)

Plan limits (OR-semantic):

• Free: 1 project AND 5 workers
• Min ($4.99/mo): 5 projects OR 25 workers total
• Max ($11.99/mo): 20 projects OR 150 workers total

402 response на POST /onboarding/setup або POST /projects/:name/workers коли ліміт перевищено: { error: "plan_limit_reached", reason: "projects_limit"|"workers_limit", current, limit, plan, message }

Admin-користувачі (role=admin) обходять plan-limit перевірку повністю — вони оператори, а не платні тенанти.

Beta-тестери (subscriptions.plan='beta', Phase 52 F&F) також обходять — необмежена кількість проєктів/воркерів плюс усі Max-фічі. Призначається вручну: UPDATE subscriptions SET plan='beta' WHERE user_id=?.

Bugfix (issue #25): POST /projects/create (Quick Start, Phase 50.2) раніше падав із ownerChatId is not defined через typo — виправлено, audit-actor тепер коректно записується.

Bugfix (issue #26): allocatePort() для нових проєктів тепер пробить реальні TCP-bindings (ss -tln), а не лише registry. Раніше міг видати порт, зайнятий не-registry сервісом (NotebookLM bridge :19213, internal bridges) → workspace bot падав на EADDRINUSE.

Auth flow (Phase 50.1): /api/auth/register і /api/auth/login тепер повертають JWT навіть для unverified email + flag needs_verification: true. Сенситивні дії (trial grant, billing, invites) перевіряють email_verified окремо. Rate limit на signup: 3 / IP / 24h.

Проєкти (9 ендпоінтів)

POST /projects/create — body:

{
  "technical_name": "string",
  "displayName": "string",
  "description": "string",
  "icon": "string",
  "color": "string"
}

GET /projects/:name/logs — query: category, lines

GET /projects/:name/metrics — query: since, until

Воркери (11 ендпоінтів)

POST /projects/:name/workers — body:

{
  "label": "string",
  "icon": "string",
  "type": "terminal | telegram",
  "model": "string",
  "max_turns": 20,
  "tools": ["Read", "Write", "Bash"],
  "system_prompt": "string",
  "focus_dirs": ["src/", "docs/"]
}

max_turns за замовчуванням 20 (раніше було 5, що спричиняло помилку "Reached max turns" у багатоступеневих діалогах із tool calls).

POST /projects/:name/restart — query: worker_id

Файли та сховище (8 ендпоінтів)

GET /projects/:name/files — query: path

GET /projects/:name/files/read — query: path, raw

Навички / Skills (18 ендпоінтів)

Навички проєкту

Глобальний маркетплейс

Еволюція та оновлення

Форки навичок

Чат та повідомлення

Wiki (4 ендпоінти)

Аналітика (4 ендпоінти)

Marketplace та Sage (8 ендпоінтів)

Пам'ять та Knowledge

Документація (глобальна, без auth)

GET /docs/tree — query: lang (опціональний)

• Спочатку шукає docs/public/<lang>/index.md, fallback на docs/public/index.md
• Response includes: sections, files, served_lang, is_fallback, requested_lang

GET /docs/file — query: path (обов'язковий), lang (опціональний)

• Resolve order: docs/public/<lang>/<path> → docs/public/<path> (EN fallback)
• Response includes: path, content, size, modified, served_lang, is_fallback, requested_lang
• 403 на path traversal, 404 на missing file
• Phase 52.1.3 — додано lang параметр для UK перекладу

Система

Коди помилок

GitHub Integration (Phase 49.3)

Supported events: push, pull_request, workflow_run, issues. Сповіщення йдуть у Telegram власника проєкту.

Account Security (Phase 45.4)

Безпека

• Multi-tenancy: кожен :name endpoint перевіряє ownership через chatId з JWT
• Project name validation: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ (max 64 символи)
• Path traversal protection: safePath() на всіх user-controlled шляхах
• File upload: max 100MB, заблоковані розширення (.exe, .bat, .sh)
• CORS: whitelist origins через CRM_ALLOWED_ORIGINS
• SSRF protection: allowlist на handleScoutAnalyze — лише HTTPS + дозволені хости
• Internal endpoints: відхиляють запити з proxy-заголовками (X-Forwarded-For, X-Real-IP)
• At-rest encryption (Phase 45): API-ключі та chat messages зашифровані AES-256-GCM
• Security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff
• PII sanitization: emails, API-ключі, JWT автоматично редагуються з JSONL логів

Phase 63 — Консолідація UI/UX + відстеження використання токенів (2026-05-21, #148)

Новий endpoint:

• POST /api/internal/usage/log (тільки loopback) — записує рядок у token_usage_log. Body: { project_name, owner_id, worker_id?, input_tokens, output_tokens, cache_tokens, total_tokens }. Викликається з child-bot/bot.ts як fire-and-forget після кожного виклику Claude (callClaudeOnce + callWorker text path). Не потребує auth header — /api/internal/* доступний лише з localhost і блокується nginx для зовнішніх запитів.
• GET /api/crm/account/usage — історія використання токенів для авторизованого користувача (описана в таблиці Onboarding вище).

Зміни в claude-runner.ts:

• callClaudeOnce + callWorker text path: тепер завжди --output-format json (раніше text для non-trial). JSON parse витягує result як output text і usage для логування. Trial consume flow незмінний.
• Новий logUsage? dep у ClaudeRunnerDeps — callback (workerId, { input, output, cache }) => void.

UI зміни (не API):

• UserDropdown: компонент UsageCard з total tokens + "Details →" при відкритті; warning dot на avatar коли trial balance < 20%.
• BillingPage: секція Token Usage з totals bar + таблиця 50 рядків. Plan Enterprise (в розробці). Toggle details на кожній картці.
• OnboardingProgressPill: перероблений як inline header dropdown (більше не modal wizard).
• WorkerSelector: семантичні CSS-змінні --worker-{role} замість Tailwind chart токенів.