API для LMS и интеграторов

A Generator API 0.3.0 — 69 путей. Сценарий «только движок» (06-api.md §6): загрузить Problem → посчитать → сохранить и опубликовать расписание.

Quickstart за 10 минут

TS-клиент (@alrevion/ag-client, sdk/ts) с рабочими примерами на sk_test_-ключе: sdk/ts/QUICKSTART.md в репозитории. Сквозной сценарий целиком, включая правку урока и MPP-пересчёт: api/scripts/scenario-a.mjs.

Ключ песочницы по умолчанию не может менять настройки организации — orgs:write выдаётся отдельно от остальных прав (см. раздел «Организации» ниже).

Движок: Problem, задачи, проверки

POST /v1/problems upload a Problem
GET /v1/problems/{problem_id} Problem metadata and input validation status
GET /v1/problems/{problem_id}/content The stored Problem, streamed as uploaded or built
POST /v1/problems/{problem_id}/precheck feasibility prechecks (Free plan — 202 job)
POST /v1/problems/{problem_id}/solve start generation
POST /v1/problems/{problem_id}/explain minimal conflict sets and suggested relaxations (job `explain`)
POST /v1/problems/{problem_id}/resolve MPP re-solve against a baseline, optionally repairing one moved lesson (job `resolve_mpp`)
POST /v1/validate independent validator (Free plan — 202 job)
POST /v1/moves/candidates candidates for a cell (Free plan — 202, job `check.moves` op=candidates)
POST /v1/moves/check check a lesson move (Free plan — 202, job `check.moves` op=check; our UI checks moves in the browser)
POST /v1/moves/suggest top-N slots for a lesson (Free plan — 202, job `check.moves` op=suggest)
POST /v1/substitutions/recommend substitution candidates (check.recommend) or day reshuffle (reshuffle_day)
POST /v1/constraints/parse phrase → draft constraint (confirmed_at = null) + "understood as"
GET /v1/norms/profiles norms catalogue
GET /v1/norms/profiles/{code} one norms profile with editions
POST /v1/compliance/report compliance report (job `check.compliance`; JSON only, PDF in phase 4)

Задачи и вебхуки

GET /v1/jobs List jobs of the organization (newest first)
GET /v1/jobs/{job_id} job status (poll every 2–5 s)
POST /v1/jobs/{job_id}/cancel cancel
GET /v1/jobs/{job_id}/result Result (03 §9), streamed as stored

Платформа

GET /v1/webhooks Active webhook endpoints
POST /v1/webhooks Register a webhook endpoint (secret shown once)
DELETE /v1/webhooks/{webhook_id} Disable an endpoint
GET /v1/webhooks/{webhook_id}/deliveries Delivery log (last 50)
GET /v1/usage Tariff limits and this month's usage (jobs, CPU seconds, LLM tokens)
GET /v1/health Liveness — D1, the queue, alerts and the last successful job (P3-52)

Организации и хранение (справочники, расписания)

GET /v1/memberships Organizations of the signed-in user with the role (org switcher)
POST /v1/invites/accept Accept an invitation (session whose email matches the invited address)
GET /v1/organizations/{org}/invites Invitations of the organization (owner/admin)
POST /v1/organizations/{org}/invites Invite a person by email (owner/admin); the link goes out through email-api
DELETE /v1/organizations/{org}/invites/{invite_id} Revoke a pending invitation
GET /v1/organizations organizations visible to the caller
POST /v1/organizations create an organization
GET /v1/organizations/{org} organization, settings (calendar, locale), norms profile
PATCH /v1/organizations/{org} update (settings are merged, JSON Merge Patch)
DELETE /v1/organizations/{org} delete the tenant (P3-26)
GET /v1/organizations/{org}/teachers teachers (confirmed data; drafts with ?draft=true)
PUT /v1/organizations/{org}/teachers bulk upsert teachers (≤ 500 items, ≤ 1 MB, one D1 round trip)
GET /v1/organizations/{org}/student-sets student-sets (confirmed data; drafts with ?draft=true)
PUT /v1/organizations/{org}/student-sets bulk upsert student-sets (≤ 500 items, ≤ 1 MB, one D1 round trip)
GET /v1/organizations/{org}/rooms rooms (confirmed data; drafts with ?draft=true)
PUT /v1/organizations/{org}/rooms bulk upsert rooms (≤ 500 items, ≤ 1 MB, one D1 round trip)
GET /v1/organizations/{org}/buildings buildings (confirmed data; drafts with ?draft=true)
PUT /v1/organizations/{org}/buildings bulk upsert buildings (≤ 500 items, ≤ 1 MB, one D1 round trip)
GET /v1/organizations/{org}/subjects subjects (confirmed data; drafts with ?draft=true)
PUT /v1/organizations/{org}/subjects bulk upsert subjects (≤ 500 items, ≤ 1 MB, one D1 round trip)
GET /v1/organizations/{org}/bell-schedules bell-schedules (confirmed data; drafts with ?draft=true)
PUT /v1/organizations/{org}/bell-schedules bulk upsert bell-schedules (≤ 500 items, ≤ 1 MB, one D1 round trip)
GET /v1/organizations/{org}/activities activities (confirmed data; drafts with ?draft=true)
PUT /v1/organizations/{org}/activities bulk upsert activities (≤ 500 items, ≤ 1 MB, one D1 round trip)
GET /v1/organizations/{org}/constraints constraints (confirmed data; drafts with ?draft=true)
PUT /v1/organizations/{org}/constraints bulk upsert constraints (≤ 500 items, ≤ 1 MB, one D1 round trip)
POST /v1/organizations/{org}/confirm Confirm drafts (draft_data → data in one SQL statement, audited)
POST /v1/organizations/{org}/problems P3-21 — build a Problem from the directories (SQL aggregate → storage, never parsed)
GET /v1/organizations/{org}/api-keys API keys of the organization (no secrets)
POST /v1/organizations/{org}/api-keys Create an org-bound API key (shown once; environment follows the organization)
DELETE /v1/organizations/{org}/api-keys/{key_id} Revoke a key (other edge isolates honour it within 60 s)
GET /v1/organizations/{org}/labels Person labels (names) for client-side texts — the only place names leave the API
PUT /v1/organizations/{org}/labels Upsert labels by code (≤ 200 per request)
GET /v1/organizations/{org}/schedules schedule versions
POST /v1/organizations/{org}/schedules new version from a solve job result, or an empty manual one for a problem
GET /v1/organizations/{org}/schedules/{schedule_id} version metadata (ETag = rev)
POST /v1/organizations/{org}/schedules/{schedule_id}/publish publish
POST /v1/organizations/{org}/schedules/{schedule_id}/archive archive a version
GET /v1/organizations/{org}/schedules/{schedule_id}/lessons current revision, streamed (ETag = rev)
PUT /v1/organizations/{org}/schedules/{schedule_id}/lessons replace with a whole new revision (Free plan; per-lesson PATCH after Paid)
GET /v1/organizations/{org}/absences teacher absences overlapping [from, to]
POST /v1/organizations/{org}/absences record an absence (teacher code, dates, reason code)
DELETE /v1/organizations/{org}/absences/{absence_id} remove an absence
POST /v1/organizations/{org}/absences/{absence_id}/recommend M6 — substitution candidates (check.recommend) or a reshuffled day (reshuffle_day) for a stored schedule
GET /v1/organizations/{org}/substitutions proposed and confirmed substitutions (history)
POST /v1/organizations/{org}/substitutions propose a substitution (emits substitution.proposed)
POST /v1/organizations/{org}/substitutions/{substitution_id}/confirm confirm (emits substitution.confirmed, audited)

Онбординг

POST /v1/organizations/{org}/onboarding Start an onboarding session
GET /v1/organizations/{org}/onboarding/{session_id} Session status and summary (files, chunk progress for resuming, tokens, precheck result)
POST /v1/organizations/{org}/onboarding/{session_id}/files Store a source file (tmp90/, only if the user agreed)
POST /v1/organizations/{org}/onboarding/{session_id}/chunks Store an encoded cell chunk (names already replaced by codes)
POST /v1/organizations/{org}/onboarding/{session_id}/llm Groq proxy for one chunk (gpt-oss-120b, reasoning high, JSON Schema mode)
POST /v1/organizations/{org}/onboarding/{session_id}/voice Phrase audio → tmp30/ + Groq whisper-large-v3 → text (≤ 2 min)
PUT /v1/organizations/{org}/onboarding/{session_id}/questions Questions to the school from the merge step (≤ 200; each needs text and at least one source)
POST /v1/organizations/{org}/onboarding/{session_id}/check Build a Problem "as if drafts were confirmed" and run inputcheck + precheck
GET /v1/organizations/{org}/questions Questions to the school, with sources and defaults
POST /v1/organizations/{org}/questions/{question_id}/answer Answer a question (or take the default)

audit

POST /v1/organizations/{org}/audit/files Store a schedule file for the free audit (tmp30/, deleted after 30 days)

Полный машиночитаемый контракт (OpenAPI 3.1, тот же файл, что и выше): api/openapi/openapi.json в репозитории, пересобирается npm run openapi вместе с ag-api.