API керування: автоматизація панелі

Для розробників, у коді: автоматизація панелі — кожен ресурс із дієсловами й додатковими діями, обмеження на власника, пагінація, скорочена відповідь і де лежить згенерований довідник.

API керування — те, чим говорить панель. Це REST API під /api/, автентифікований ключем керування (Authorization: Api-Key <ключ>, Автентифікація), і кожен рядок, який він повертає, належить власнику ключа. Повний згенерований довідник — кожне поле кожного серіалізатора — на /api/docs/ (Swagger) і /api/redoc/, зі схеми OpenAPI на /api/schema/. Ця сторінка — карта.

Домовленості


ідентифікатори	усюди UUID
обмеження	список — власника; `?site=<uuid>` звужує його до одного з його сайтів — хибний id дає порожній список, коректний чужий — `404` на insights, overview, analytics і content-gaps
пагінація	за номером сторінки, 50 на сторінку, без `?page_size` — крім джерел і заявок (`?page`, `?page_size` ≤ 200) і розмов (курсор, 30 на сторінку, `?page_size` ≤ 100, порядок `-updated_at`)
скорочена відповідь	`?detail=false` на GET сайтів, джерел, помічників чи віджетів повертає лише поля, що ідентифікують рядок (`id`, `name` / `title`, `site`, `code` / `url`) — на 94 % менше на реальних даних; будь-яке нерозпізнане значення означає повну відповідь
невдачі	`403` на будь-яку невдалу автентифікацію; `404` на чужий рядок; `403` з `detail`, що називає ліміт, на ліміт тарифу; `400` на валідацію
ліміти частоти	обмежено лише `POST /api/onboarding/analyze/` (20 на хвилину на власника); перевірка інструмента обмежена нижче за течією (30 на хвилину)

Ресурси

Ресурс	Дієслова і додаткові дії	Примітки
`/api/sites/`	CRUD (створення — `403` понад кількість сайтів у плані; перехід на менший план сайти не видаляє); `GET {id}/sitemap-suggestions/?url=`; `POST {id}/import-sitemap/` `{url?}` → `202`; `POST {id}/provision/` `{profile}` → `202`	`detail=false`: `id`, `name`
`/api/sitemaps/`	CRUD; `POST {id}/import/` → `202`	`?site=`
`/api/sources/`	CRUD (створення — `403` на стелі сторінок тарифу; створення не обробляє, викличте `POST {id}/process/`); `POST {id}/process/`; `POST process-unprocessed/`; `POST process-stale/?before=`; `POST process-batch/` `{ids}`; `POST delete-batch/` `{ids}`; `GET stats/`; `GET {id}/chunks/`	фільтри `site`, `status` (кілька), `tag`, `is_page`, `ids`; `search` (назва/url, буквально), `q` (семантичний); `ordering` за `created_at`, `last_synced_at`, `title`, `chunk_count`, `status`
`/api/tags/`	CRUD	`?site=`
`/api/agents/`	CRUD (`409` на видалення, поки його використовує віджет); `POST persona/generate/`, `POST persona/improve/`	`detail=false`: `id`, `name`, `code`, `site`
`/api/widgets/`	CRUD; `GET {id}/install-snippet/?key=`; `POST` / `DELETE {id}/launcher-image/`	`detail=false`: `id`, `name`, `site`; `custom_css` задається тут і більше ніде в панелі
`/api/widget-faqs/`	CRUD	усі чіпи віджетів власника; без фільтрів `?widget=` і `?site=`
`/api/api-keys/`	CRUD; `POST {id}/rotate/` → `201`; `GET {id}/reveal/` (лише ключі віджета, інакше `403`)	`?site=` повертає ключі віджета цього сайту плюс усі ключі керування; `allowed_origins` — JSON-масив origin
`/api/custom-tools/` · `/api/custom-tool-secrets/` · `/api/custom-events/`	CRUD; інструменти: `POST {id}/test/` `{params, language}`	`value` секрету — лише запис; створення на тарифі без інструментів → `403`
`/api/conversations/`	list, retrieve, destroy; `POST delete-all/?site=`	курсорна пагінація; `?q=`, `?insufficient=`, `?created_after=`, `?created_before=`
`/api/handoff-requests/`	list, retrieve, update, destroy; `POST mark-batch/` `{ids, status}`; `POST delete-batch/` `{ids}`	`?status=`, `?source=`, `?received_after=`, `?received_before=`, `?search=` (лише питання і коментар — контакт зашифрований)
`/api/operations/` · `/api/provisioning/`	лише читання; `?active=true` на operations, `?active` на provisioning	прогрес пакетних операцій і запуск онбордингу
`/api/notifications/`	list; `POST {id}/read/`, `POST read-all/`, `GET unread-count/`	`?unread=true`
`/api/search/`	`GET ?q=`	пошук панелі по всьому обліковому запису власника (сайти, джерела, помічники, віджети, розмови…); `?site=` звужує його до одного сайту
`/api/overview/` · `/api/analytics/` · `/api/content-gaps/` · `/api/insights/`	GET	`?site=` обов’язковий на перших трьох; analytics приймає `from`, `to`, `period`, `breakdown`, `limit` і дванадцять фільтрів-вимірів; insights приймає `?route=`, `?area=`
`/api/languages/` · `/api/llm-models/` · `/api/voices/` · `/api/orb-skins/` · `/api/credit-plans/` · `/api/credit-packs/`	каталоги лише для читання, без пагінації	`?active` на мовах і моделях; `?lang=`, `?provider=` на голосах
`/api/billing/` і підшляхи	тариф акаунта, використання, платежі, оплата, скасування, зміна тарифу, докупівля	панельні; скрипту рідко потрібні
`/api/me/` · `/api/account/export/`	акаунт; JSON-експорт усього, що він містить	`DELETE /api/me/` потребує пароля або підтвердження

Три речі, які варто знати до скриптів

Записи — це PATCH. Надсилайте лише поля, які змінюєте; панель робить так само, і саме тому поле, якого вона більше не пропонує, зберігає те, що власник колись зберіг.
Обробка асинхронна, і створення — це не обробка. Нове джерело зберігається й чекає: викличте POST /api/sources/{id}/process/ (або process-unprocessed/). Далі обробка йде у воркері; опитуйте GET /api/operations/?active=true або status джерела.
Змінене джерело скидає кеші помічника — підвищується content_version, а зі зміною маршрутів і версії конфігурації віджета, — тож руками нічого скидати не треба.