Add a website as a knowledge source (attestation required); starts the first sync
POST/v1/knowledge_bases/:kb_id/sources
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.
attestation is required: accepted: true and the current text_version from GET /v1/knowledge_module → web.attestation (otherwise 422 attestation_required, also when the object is missing or malformed). On your organization's first website source, and again after the website-source terms change, terms_acceptance for the current web.terms.version is required as well (otherwise 422 terms_acceptance_required). The platform records who accepted, when, from which IP address and which text version; the IP address is never returned by the API.
Checks, in this order: website sources switched off (403 web_sources_disabled, module_disabled) → URL rules (422 https_required, source_url_rejected) → domain blocked by the platform (403 domain_blocked) → unverified sites not accepted on the platform right now (403 domain_not_verified; a source created with start_sync: false is still accepted) → sources per knowledge base (409 resource_limit_reached, limit_name: max_sources_per_kb) → the same site twice (409 duplicate_source) → findings of the preview named in preview_id (422 robots_disallowed; 422 ai_signal_optout only with start_sync: true) → attestation and terms. With start_sync: true the knowledge-base and billing checks of an upload apply as well (409 kb_suspended, kb_deleting, trial_kb_frozen; 402 payment_suspended; 503 maintenance_mode).
An AI-usage opt-out found by the preview on an unverified domain refuses only a create with start_sync: true: with start_sync: false the source is added without fetching anything, so you can verify the domain first (platform Domains, /v1/domains) and then start the first sync. Every later sync still applies the AI-usage rule of the tier it has then (unverified: the sync stops; verified: a warning). A robots.txt that disallows the start URL is refused either way: verification never overrides robots.txt. A source added under a domain your organization has already verified (covering its whole scope) starts with tier: verified. A source created with a completed preview shows that preview's AI-usage findings in ai_signal at once, before its first sync.
Fetching is free. Each new or changed page is billed like an upload (processing tokens and storage); unchanged pages cost nothing.
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 503 maintenance_mode during maintenance; refused with 403 module_disabled while knowledge bases are switched off on the platform.
Request
Responses
- 201
- 402
- 403
- 404
- 409
- 422
- 503
Created.
trial_exhausted, insufficient_credits, credit_limit_exceeded, payg_spend_cap_exceeded, payment_suspended — details.price_card_url always set. After the free trial, knowledge bases are billed pay-as-you-go for every organization (from the prepaid wallet or on the postpaid invoice); no plan or commitment covers them.
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
maintenance_mode, knowledge_unavailable, retrieval_unavailable, billing_unavailable — Retry-After header set