Discover a website without adding it (asynchronous; poll the preview)
POST/v1/knowledge_bases/:kb_id/sources: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.
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; refused with 403 module_disabled while knowledge bases are switched off on the platform.
Request
Responses
- 202
- 403
- 404
- 409
- 422
- 429
Preview started.
scope_missing, kb_not_in_allowlist, role_insufficient, actor_not_permitted, tenant_suspended, module_disabled (knowledge bases switched off on the platform: an operation that creates data or starts processing, for an organization that still has knowledge bases), web_sources_disabled, domain_blocked, domain_not_verified (website sources)
not_found (absent or owned by another organization — identical), module_disabled
idempotency_key_conflict, idempotency_in_progress, version_conflict, duplicate_content, kb_suspended, kb_deleting, document_deleting, document_not_ready, invalid_document_state, trial_kb_frozen, resource_limit_reached, export_in_progress, source_sync_in_progress, invalid_source_state, duplicate_source
validation_failed, invalid_identifier, metadata_*, filter_invalid, query_too_long, batch_too_large, file-type codes, https_required, source_url_rejected, robots_disallowed, ai_signal_optout, attestation_required, terms_acceptance_required
rate_limited, concurrency_limited — Retry-After header set