Web sources
Index a website into a knowledge base: preview, add, sync, runs, pages and held deletions.
📄️ List the knowledge base's website sources
**Access:** API key scope `knowledge:read` or `knowledge:write`; portal users: any member of the organization; the knowledge base in the path must be on the key's access list.
📄️ Add a website as a knowledge source (attestation required); starts the first sync
Adds a website to the knowledge base. With `start_sync: true` (the default) the first sync run is queued at once and returned in `last_run`.
📄️ Discover a website without adding it (asynchronous; poll the preview)
Discovers a website without adding it: no source, page or run is stored, only the preview. Checked at once: URL rules (422 `https_required`, `source_url_rejected`), domain blocked by the platform (403 `domain_blocked`), website sources switched off (403 `web_sources_disabled`) and previews per hour (429 `rate_limited`, `limit_name: web.previews_per_hour`). The discovery itself runs asynchronously (at most 20 requests to the site, within the site's shared request budget): poll `GET …/source_previews/{preview_id}` until `status` is `completed` or `failed`, typically a few seconds. A preview is kept for 1 hour. Replaying the request with the same `Idempotency-Key` returns the original 202 body and counts once against the hourly limit.
📄️ Result of a website preview
**Access:** API key scope `knowledge:write`; portal users: organization admins and owners; the knowledge base in the path must be on the key's access list.
📄️ Get a website source
**Access:** API key scope `knowledge:read` or `knowledge:write`; portal users: any member of the organization; the knowledge base in the path must be on the key's access list.
📄️ Rename, change the scope, pause or resume a website source
Status changes: `active`, `syncing`, `held` or `blocked_by_site` → `paused`; `paused` or `blocked_by_site` → `active`; anything else is 409 `invalid_source_state`. Pausing cancels a running sync. Resuming a source that still has an unresolved held run returns it to `held`. Resuming a source whose domain is blocked by the platform is 403 `domain_blocked`.
📄️ Delete the source and all its page documents (asynchronous)
The source becomes `deleting`, a running sync is cancelled, and every page document is deleted like any other document (one `knowledge.document.deleted` webhook per page). Idempotent: 202 again while deleting.
📄️ Start a manual sync run
Starts a manual sync run. 409 `source_sync_in_progress` while a run is queued, running or waiting for budget. 409 `invalid_source_state` when the source is `paused`, `held`, `blocked_by_site`, `disabled_by_admin` or `deleting` (set it `active` first), and while an earlier held run is unresolved, even if the source was paused and resumed meanwhile. 429 `rate_limited` (`limit_name: web.manual_sync_cooldown_minutes`) when the previous run of this source started less than the cooldown ago. 403 `domain_blocked`, `web_sources_disabled` or `domain_not_verified`. The knowledge-base and billing checks of an upload apply (409 knowledge-base state codes, 402 `payment_suspended`, 503 `maintenance_mode`). Pages that did not change cost nothing.
📄️ Runs of a source, newest first
**Access:** API key scope `knowledge:read` or `knowledge:write`; portal users: any member of the organization; the knowledge base in the path must be on the key's access list.
📄️ Get a sync run
**Access:** API key scope `knowledge:read` or `knowledge:write`; portal users: any member of the organization; the knowledge base in the path must be on the key's access list.
📄️ Apply or discard the removals of a held run
Only for a run in `held` (otherwise 409 `invalid_source_state`). `apply_deletions` deletes the held pages' documents; `discard_deletions` keeps them indexed, and the next run evaluates them again. A decision is recorded once: the run keeps `status: held` and gets `deletion.decision` and `deletion.decided_at`; sending the same decision again returns 200, a different one is 409 `invalid_source_state`. Only the hold is cleared: a `held` source becomes `active`, a `paused` or `disabled_by_admin` source keeps its status, a `deleting` source refuses (409). The pages concerned are the run's `pending_removal` pages when it ended; pages you deleted meanwhile are skipped.
📄️ Pages of a source (URL ↔ document), filterable by status / skip reason
**Access:** API key scope `knowledge:read` or `knowledge:write`; portal users: any member of the organization; the knowledge base in the path must be on the key's access list.