CRM API — Справочник endpoints

Arc OS — The Orchestration System for AI Teams

Общая информация

Аутентификация

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

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

Ошибки авторизации

Endpoints по категориям

Аккаунт и настройки

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

Onboarding Checklist (Phase 54.1, issue #56)

Post-wizard 5-шаговый чеклист вовлечённости. Каждый шаг (workers, cli, skill, bot, issue) принимает статус completed или skipped. Мутации идемпотентны: повторный идентичный POST возвращает тот же state, не пишет дубликат в activity_log. Replay не сбрасывает state, только снимает dismissed_at — UI снова показывает панель с тем же прогрессом.

SSOT для funnel-метрик (Phase 54.6 / issue #61) — события в activity_log (event_type LIKE 'onboarding_%'). Таблица onboarding_progress — derived cache: UI рендерится одним запросом вместо агрегации по событиям.

Beta Feedback (Phase 53.3)

POST /feedback — валидация body: type ∈ {bug,feature,other}, title ≤200 chars, description ≤5000 chars. Успех → {ok: true, type, title}. Telegram ping форматируется как 🐞/💡/📝 New <type> feedback ... From: <user> Title: <title> + первые 400 символов описания.

Плавающий виджет в FeedbackWidget.jsx (CRM дашборд) автоматически передаёт browser (UA + viewport + locale) и project (technical_name активного проекта).

Beta Invites (Phase 52.1, только admin)

Обновление auth flow: POST /api/auth/register теперь требует поле invite_code (Phase 52.1 closed бета). Без кода → 403 {error: "invite_required"}. Невалидный/использованный код → 403 {error: "invalid_invite"}.

Billing (Phase 51)

Plan limits (OR-semantic):

• Free: 1 проект AND 5 воркеров
• Min ($4.99/mo): 5 проектов OR 25 воркеров total
• Max ($11.99/mo): 20 проектов OR 150 воркеров total

Ответ 402 на 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 — они операторы, а не платные тенанты.

Бета-тестеры (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 из-за опечатки — исправлено, 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 + флаг needs_verification: true. Чувствительные действия (trial grant, billing, invites) проверяют email_verified отдельно. Rate limit на signup: 3 / IP / 24h.

Проекты (9 endpoints)

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 endpoints)

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 endpoints)

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

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

Скилы / Skills (18 endpoints)

Скилы проекта

Глобальный marketplace

Эволюция и обновления

Форки скилов

Чат и сообщения

Wiki (4 endpoints)

Аналитика (4 endpoints)

Marketplace и Sage (8 endpoints)

Память и 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)

Поддерживаемые события: 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 keys, JWTs автоматически редактируются из JSONL логов

Phase 53.13 — type-safety baseline (2026-05-10)

Не изменение поведения endpoints — только внутренние типы. tsc --noEmit теперь блокирует push/CI:

• Интерфейс ChildBot консолидирован в shared/routes/_utils.ts (3× дубликата объединены). bot_username, heartbeat_file, health_endpoint, status сделаны optional — отражают runtime-state (DB-enriched workspace entries часто без них).
• requireAdmin() в shared/routes/system.ts теперь возвращает Response | { userId } вместо { ok, ... } — упрощает narrowing через instanceof Response. Внешнее поведение (коды 401/403, тела ответов) неизменно.
• workers.ts DEFAULT_WORKERS потерял as const (для совместимости с mutable callsites); парсинг body для tools / focus_dirs теперь строго через Array.isArray вместо ||-fallback.

Phase 53.15 — Sentinel Sprint 1 (2026-05-10)

Изменения поведения auth + admin endpoints (Sentinel audit P0 fixes):

• POST /api/auth/login — когда requires2fa=true, ответ теперь {requires2fa: true, challenge_token} вместо {requires2fa: true, userId}. Frontend должен передавать challenge_token на следующем шаге.
• POST /api/auth/2fa/login — body shape: {challenge_token, code} вместо {userId, code}. Токен одноразовый, TTL 5 мин. Без валидного токена endpoint возвращает 401 "Invalid or expired challenge — restart login". Per-userId rate-limit 5 попыток / 15 мин → 429.
• POST /api/crm/skills + PUT /api/crm/skills/:id + DELETE /api/crm/skills/:id + POST /api/crm/skill-updates/:id/approve + POST /api/crm/skill-updates/:id/reject — только admin. Не-admin → 403 Forbidden — admin only. Без auth → 401.
• Nginx rate-limit на /api/auth/* — 5 req/min/IP (burst=10 nodelay → 429). То же на /api/webhooks/github (30 req/min/IP, burst=20).
• HSTS — заголовок Strict-Transport-Security: max-age=31536000; includeSubDomains; preload теперь шлёт каждый HTTPS-ответ. HTTP запросы → 301 redirect на HTTPS.
• X-Frame-Options: DENY вместо SAMEORIGIN.

Phase 53.21 — Sentinel P2 batch 2 (2026-05-12)

• POST /api/crm/feedback — теперь требует чтобы caller мог получить доступ к claimed body.project (проверка canAccessProject). Не-владелец проекта → 403 "Project not accessible". Пустой/отсутствующий project по-прежнему разрешён (global feedback).
• POST /api/internal/trial/consume — body shape изменён: {project, owner_id, tokens} вместо {project, tokens}. owner_id обязательный, верифицируется против projects.owner_id в DB. 404 на неизвестный проект, 403 при несовпадении owner. Caller (child-bot/claude-runner.ts) propagates ARC_TRIAL_OWNER env injected by worker-spawn.ts.

Phase 53.18 — tmux secret-leak fix (2026-05-11)

Не изменение поведения endpoints — только рефакторинг internal spawn paths.

• POST /api/crm/onboarding/setup (через shared/routes/onboarding.ts:startWorkspaceBot) — способ запуска workspace-mode child-bot изменён с bash -c "export X='val'; bun run bot.ts" на tmux -e VAR=val ... bun run bot.ts. Значения токенов больше не попадают в /proc/PID/cmdline. Внешне: 0 изменений (response body, status codes, поведение идентично).

Phase 53.16 — Sentinel Sprint 2 (2026-05-10)

Изменения поведения endpoints после hardening 13 × P1:

• OAuth callback — Redirect URL использует #token= fragment вместо ?token= query (Sentinel P1-8). Frontend читает из window.location.hash (с fallback на ?token= на один deploy cycle).
• /api/crm/analytics/activity + /api/crm/analytics/sidebar — query теперь scoped по owner_id залогиненного пользователя. Не-admin видит только свои проекты. Раньше утекали первые 80 char каждого assistant message + project names + worker IDs всех тенантов (Sentinel P1-4).
• PUT /api/crm/projects/:name/files/save — добавлена проверка isProtectedPath(). .env / CLAUDE.md / .git/* / .claude/* теперь 403 "Protected path" (раньше можно было перезаписать) (Sentinel P1-3).
• POST /api/crm/projects/:name/files/mkdir + /files/create — body.name с .., ., /, \ → 400. Повторный запуск safePath() после join() (Sentinel P1-2).
• /ws/local-bridge — JWT chatId сохраняется при upgrade. Init message с project_name не принадлежащим пользователю → close 1008 Forbidden — project not accessible. Раньше любой пользователь мог init'нуть bridge на чужой проект (Sentinel P1-5).
• CSP — frontend HTML (через docker/nginx.conf) теперь шлёт строгий CSP: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https:; font-src 'self' data:; connect-src 'self' https://arc-os.co wss://arc-os.co; frame-ancestors 'none'; base-uri 'self'; form-action 'self'. API JSON CSP потерял 'unsafe-inline' (Sentinel P1-10).
• extractChatId internal helper — теперь verifyToken'ит подпись перед декодированием (Sentinel P1-6, defense-in-depth для будущих skipAuth routes).
• Recovery key encrypted format — новые ключи хранятся как v2:<base64-salt>:<payload> (per-key 16-byte random salt). Старые (без v2: prefix) работают через legacy fallback (Sentinel P1-13).
• CEO_CHAT_ID — теперь env-first (с warning fallback на bot_registry). Захардкоженный 474903718 удалён из 6 файлов (Sentinel P1-14).
• Nginx X-Forwarded-For — overwrite вместо append во всех 17 callsites (Sentinel P1-11). Хелпер clientIp читает LAST XFF segment (Sentinel P1-7).

Phase 55 — Cosmic Editorial login (2026-05-13)

Новые endpoints для magic-link sign-in:

• POST /api/auth/magic-link/request — body { email }. Генерирует 10-min single-use токен в ephemeral_tokens (тип magic_link), отправляет ссылку https://<host>/?magic_token=<token> через email-провайдер. Anti-enumeration: всегда 200 OK с телом { ok: true, message: "If the account exists, a magic link has been sent" } (даже если email не существует). Rate-limit: 3/min per (IP+email) + 5/10min per email — тот же контракт что forgot-password. Неудачный путь проходит timing pad.
• POST /api/auth/magic-link/verify — body { token }. Consume single-use, returns { ok: true, token: <jwt>, userId } при успехе или 401 "Invalid or expired magic link". Side effect: user.email_verified = true + last_login обновляется (inbox proof = verification).

EphemeralTokenType union расширен: теперь содержит "magic_link" наряду с существующими oauth_state / password_reset / email_verification / tfa_challenge.

Frontend (CosmicCard.jsx) обрабатывает состояние magic (60-s resend countdown) и URL-параметр ?magic_token= (auto-consume → login → success animation).

Phase 56 — AI Interop / Project Context Export (2026-05-13)

Owner-only экспорт sanitized snapshot проекта как .md для передачи внешнему AI (Gemini / ChatGPT / Perplexity / Claude.ai).

• GET /api/crm/projects/:name/context-export — params: include=section1,section2,... (sections: identity / workers / architecture / issues / activity / commits / learnings; default = все 7), scanOnly=true|false, activityHours=N (1-720, default 168), commitLimit=N (1-200, default 20), issueStatus=open|closed|all. Только owner — роль admin НЕ обходит (по дизайну). CEO bypass работает. Returns { project, exportedAt, filename: "<project>-context-YYYY-MM-DD.md", scanOnly, sections, markdown, findings, stats, alertFired, preferences }. Автоматически редактирует critical findings если preferences.auto_redact_critical = false не задано. Non-scanOnly runs пишут в export_audit_log.
• GET /api/crm/projects/:name/exports — список audit (только owner). Params: limit=N (1-200, default 50). Returns { project, exports: [{ id, owner_id, exported_at, sections[], findings_critical/high/medium/low, bytes }] }.
• GET /api/crm/projects/:name/settings/export — читать prefs (только owner). Returns { project_name, always_include_emails, auto_redact_critical, notify_on_export, updated_at }.
• PATCH /api/crm/projects/:name/settings/export — обновить prefs (только owner). Body принимает любое подмножество { always_include_emails, auto_redact_critical, notify_on_export } (booleans). Returns обновлённые prefs.
• GET /api/crm/analytics/exports — агрегированная статистика (auth required, без owner gate — analytics card). Param: hours=N (1-720, default 168). Returns { total, byProject: [{ project_name, n, last }], severitySums: { critical, high, medium, low } }.

Alert: когда владелец превышает 3 экспорта за 24h AND prefs.notify_on_export = true (default OFF) — logActivity("export_alert", ...) идёт через существующий Phase 53.10 TG notify pipeline (alertFired: true в response body).

Multi-tier scanner (shared/secret-scanner.ts) — Tier 1 regex (PATTERN_REGISTRY из PII sanitizer), Tier 2 Shannon entropy ≥4.5 bits/char на ≥20-char runs, Tier 3 context heuristics (key=/token:/secret=/password=). Whitelist: UUID / git SHA / SHA-256 / repeated chars / short hex / low-entropy base58. Severity tiers (critical/high/medium/low). Производительность: <500 ms / 1 MB.

DB migration 024 — таблицы export_audit_log + export_preferences.

Phase 57 — Platform Settings (Sentinel #103 follow-up, 2026-05-15)

Super-admin управление секретами через CRM UI вместо ssh/edit-.env/paste-in-chat. Backend MVP (Stage 1 из 4 stages). Все endpoints гейтованы requireAdmin (Phase 53.15) — возвращают 403 Forbidden — admin only для не-admin, 401 Unauthorized без JWT.

• GET /api/crm/platform/settings — возвращает { items: [{ name, label, description, testable, restartTargets[], set, preview, length, lastRotated, lastRotatedBy }] }. Allowlist 9 ключей (ANTHROPIC_API_KEY, PLATFORM_ANTHROPIC_KEY, GITHUB_CLIENT_ID/SECRET, GOOGLE_CLIENT_ID/SECRET, MASTER_BOT_TOKEN, CITADEL_BOT_TOKEN, RESEND_API_KEY). Redacted preview: prefix(12)…suffix(4) + length. Полное значение никогда не покидает сервер.
• PUT /api/crm/platform/settings/:name — body { value: string ≥ 8 chars }. Атомарно пишет в vault через storeSecret(name, value) + audit row. 400 если name не в allowlist; 400 если value < 8 chars; 500 при ошибке записи в vault.
• POST /api/crm/platform/settings/:name/test — проверить против SaaS API. Anthropic → GET /v1/models с x-api-key; TG → getMe; Resend → /api-keys. OAuth client secrets standalone не testable → 501. Returns { ok: bool, reason?: string, detail?: string }. Таймаут 8 сек через AbortController.
• POST /api/crm/platform/settings/:name/restart — Bun.spawn(["nohup", "bash", "-c", "sleep 1 && tmux kill-session ... && bash start-*.sh"], { detach: true }) на привязанных tmux сессиях. Detached чтобы restart master не убил in-flight response. Returns { ok: true, restarted: [sessions], note }.
• GET /api/crm/platform/audit?limit=50&key=ANTHROPIC_API_KEY — последние записи audit лога, newest-first (limit capped 500). Опциональный фильтр по key.

Список жёсткого исключения NEVER_EXPOSE: CRM_SECRET (JWT signing) + SECRET_ENCRYPTION_KEY (vault meta-key) — даже admin запрос с валидным токеном возвращает 400 "not managed". Audit лог append-only (нет UPDATE/DELETE handler), каждое действие (включая failed) пишет row с IP + UA + email.

DB migration 026 — таблица platform_audit_log. Stage 2 (frontend PlatformSettings.jsx) — задеплоен 2026-05-15 (cbc8bac): admin-only card grid + rotate modal (<input type="password"> + retype-confirm) + audit drawer; запись sidebar фильтруется по userRole === "admin", получаемому из /api/auth/me.

Polish (2026-05-15, commit 56191b0) — реструктуризация Platform Settings UI. Поля items ответа GET /api/crm/platform/settings получают 5 новых полей: category (anthropic|oauth|telegram|email), usedIn (string[] — файлы/флоу потребляющие ключ), getFromUrl (где получить свежее значение), effectAfterRotate, riskIfLeaked. Используется frontend для рендеринга 4 секционных групп карточек + per-card сворачиваемая help-панель со структурированным контекстом (Used in / Get from / Effect / Risk). Никаких изменений поведения мутирующих endpoints (PUT/POST/restart/test).

Рефакторинг (2026-05-16) — internal cleanup shared/routes/platform.ts. Удалено 39 строк (добавлено 16), никаких изменений публичного API surface. Сигнатуры и ответы endpoints PUT/POST/restart/test/audit неизменны. Задокументировано здесь только потому что doc-coverage pre-push gate срабатывает на любой diff в shared/routes/*.ts.

Backdated activity (#117, 2026-05-16) — POST /api/mcp/issues/:project/:id/log теперь принимает опциональное поле ts (строка ISO-8601). Используется arc retro при реконструкции чтобы исторические записи попадали на свои оригинальные временные метки. Значения из будущего молча обрезаются до now внутри addActivity() (защита от случайных backdates). Невалидный ISO → 400.

Stage 3 (2026-05-15) — hot-reload OAuth + Resend secrets без restart. shared/auth.ts loadOAuthConfig() теперь читает getSecret("GITHUB_CLIENT_ID/SECRET" | "GOOGLE_CLIENT_ID/SECRET") при каждом вызове вместо process.env. Callsites в master-bot/routes/auth.ts уже вызывали getOAuthConfig() per request → 0 изменений callsite. RESEND_API_KEY уже hot-reload через shared/email.ts:47. Поведенческое изменение: PUT /api/crm/platform/settings/{GITHUB_CLIENT_ID|GITHUB_CLIENT_SECRET|GOOGLE_CLIENT_ID|GOOGLE_CLIENT_SECRET|RESEND_API_KEY} теперь вступает в силу со следующего запроса, не требует restart. restartTargets для этих 5 ключей пустой → кнопка Restart в UI скрыта. Edge case: OAuth flow с state-токеном выданным до rotation может получить 400 на callback при code-exchange — retry пользователя решает проблему. ANTHROPIC_API_KEY, PLATFORM_ANTHROPIC_KEY, MASTER_BOT_TOKEN, CITADEL_BOT_TOKEN остаются restart-required (читаются при child-bot spawn / TG long-poll init).

Phase 57.3.5 cleanup (2026-05-16) — allowlist MANAGED_KEYS сокращён с 9 до 6. Удалены: ANTHROPIC_API_KEY (операторы теперь используют единый PLATFORM_ANTHROPIC_KEY для trial-credits и platform inference; .env fallback по-прежнему работает для legacy code paths пока Sage/Karpathy не мигрируют), CITADEL_BOT_TOKEN (per-project bot относится к vault записям child:<name>:token, управляемым через worker onboarding flow — не Platform Settings). MASTER_BOT_TOKEN перепрофилирован: label → "Telegram — System Monitor Bot", description → "Server health alerts + on-demand status probes (admin-only, not a chat bot)". Phase 58 добавит monitoring loop (push alerts для worker crash / disk / RAM / SSH brute-force / CF bypass + команды /status, /health, /errors, /restart). Итоговый набор: PLATFORM_ANTHROPIC_KEY + GITHUB×2 + GOOGLE×2 + MASTER_BOT_TOKEN + RESEND_API_KEY (refs #103).

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-заголовка — /api/internal/* доступен только с localhost и блокируется nginx для внешних запросов.
• GET /api/crm/account/usage — история использования токенов для авторизованного пользователя (описана в таблице Onboarding выше).

Изменения в claude-runner.ts:

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

Изменения UI (не API):

• UserDropdown: компонент UsageCard с общим количеством токенов + «Details →» при открытии; предупреждающий dot на аватаре когда баланс trial < 20%.
• BillingPage: секция Token Usage с панелью суммарных значений + таблица 50 строк. Plan Enterprise (в разработке). Toggle details на каждой карточке.
• OnboardingProgressPill: переработан как inline dropdown в хедере (больше не modal wizard).
• WorkerSelector: семантические CSS-переменные --worker-{role} вместо Tailwind chart-токенов.