Questa pagina è pubblicata in inglese e in ucraino; qui sotto c’è la versione inglese.

Management API: automating the panel

For developers, in code: automating the panel — every resource with its verbs and extra actions, owner scoping, pagination, the lean payload, and where the generated reference lives.

The management API is what the panel speaks. It is a REST API under /api/, authenticated with a management key (Authorization: Api-Key <key>, Authentication), and every row it returns belongs to the key’s owner. The full generated reference — every field of every serializer — is at /api/docs/ (Swagger) and /api/redoc/, from the OpenAPI schema at /api/schema/. This page is the map.

Conventions


ids	UUIDs everywhere
scoping	a list is the owner’s; `?site=<uuid>` narrows it to one of their sites — a malformed id yields an empty list, a well-formed foreign one `404` on insights, overview, analytics and content gaps
pagination	page-number, 50 per page, no `?page_size` — except sources and handoff requests (`?page`, `?page_size` ≤ 200) and conversations (cursor, 30 per page, `?page_size` ≤ 100, ordered `-updated_at`)
lean payload	`?detail=false` on a GET of sites, sources, agents or widgets returns only the fields that identify a row (`id`, `name` / `title`, `site`, `code` / `url`) — 94 % smaller on real data; any unparseable value means the full payload
failures	`403` for any authentication failure; `404` for another owner’s row; `403` with a `detail` naming the limit for a plan cap; `400` for validation
rate limits	only `POST /api/onboarding/analyze/` is throttled (20 a minute per owner); a tool Test is limited downstream (30 a minute)

Resources

Resource	Verbs and extra actions	Notes
`/api/sites/`	CRUD (create `403` past the plan’s site count; a downgrade keeps every site); `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 (create `403` at the plan’s page cap — creating does not process; call `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/`	filters `site`, `status` (several), `tag`, `is_page`, `ids`; `search` (title/url, literal), `q` (semantic); `ordering` on `created_at`, `last_synced_at`, `title`, `chunk_count`, `status`
`/api/tags/`	CRUD	`?site=`
`/api/agents/`	CRUD (`409` on delete while a widget uses it); `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` is set here and nowhere in the panel
`/api/widget-faqs/`	CRUD	every chip of the owner’s widgets; no `?widget=` or `?site=` filter
`/api/api-keys/`	CRUD; `POST {id}/rotate/` → `201`; `GET {id}/reveal/` (widget keys only, else `403`)	`?site=` returns that site’s widget keys plus every management key; `allowed_origins` is a JSON array of origins
`/api/custom-tools/` · `/api/custom-tool-secrets/` · `/api/custom-events/`	CRUD; tools: `POST {id}/test/` `{params, language}`	a secret’s `value` is write-only; create on a plan without tools → `403`
`/api/conversations/`	list, retrieve, destroy; `POST delete-all/?site=`	cursor-paginated; `?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=` (question and comment only — the contact is encrypted)
`/api/operations/` · `/api/provisioning/`	read-only; `?active=true` on operations, `?active` on provisioning	batch progress and the onboarding run
`/api/notifications/`	list; `POST {id}/read/`, `POST read-all/`, `GET unread-count/`	`?unread=true`
`/api/search/`	`GET ?q=`	the panel’s search across the owner’s account (sites, sources, agents, widgets, conversations…); `?site=` narrows it to that one site
`/api/overview/` · `/api/analytics/` · `/api/content-gaps/` · `/api/insights/`	GET	`?site=` required on the first three; analytics takes `from`, `to`, `period`, `breakdown`, `limit` and the twelve dimension filters; insights takes `?route=`, `?area=`
`/api/languages/` · `/api/llm-models/` · `/api/voices/` · `/api/orb-skins/` · `/api/credit-plans/` · `/api/credit-packs/`	read-only catalogues, not paginated	`?active` on languages and models; `?lang=`, `?provider=` on voices
`/api/billing/` and its sub-paths	the account’s plan, usage, payments, checkout, cancel, plan change, top-up	the panel’s; a script rarely needs them
`/api/me/` · `/api/account/export/`	the account; a JSON export of everything it holds	`DELETE /api/me/` needs the password or a confirmation

Three things to know before scripting

Writes are PATCHes. Send only the fields you change; the panel does the same, which is how a field it no longer offers keeps whatever an owner saved.
Processing is asynchronous, and creating is not processing. A new source is saved and waits: call POST /api/sources/{id}/process/ (or process-unprocessed/). Processing then runs in a worker; poll GET /api/operations/?active=true or the source’s status.
A changed source invalidates the assistant’s caches — content_version bumps, and so do the widget-config versions when routes change — so there is nothing to flush by hand.