Create a knowledge base
POST/v1/knowledge_bases
Free of charge but subject to the knowledge-base count limit (free trial: 402 trial_exhausted with details.meter = knowledge_bases; platform limit: 409 resource_limit_reached). Only portal admins and owners and API keys with access to all knowledge bases (kb_allowlist = null) may create a knowledge base: a key limited to a list of knowledge bases (or to none) gets 403 kb_not_in_allowlist and nothing is created.
embedding_model picks the knowledge base's embedding model: the id of an entry of GET /v1/knowledge_embedding_models. Leave it out (or send null) to use the recommended model. The model is fixed for the life of the knowledge base; to use another model, create a new knowledge base. Every model in that list can be used by your organization, whether or not you also use it for inference. A refusal is 422 validation_failed with param = embedding_model: an unknown or no longer offered id (no details.reason), details.reason = model_unknown (the model was removed from the platform) or details.reason = unpriced (the model has no processing price for your organization right now). If the model cannot be checked right now, the call is a retryable 503 knowledge_unavailable and no knowledge base is created.
Access: API key scope knowledge:write; portal users: organization admins and owners; a key limited to a list of knowledge bases (or to none) is refused with 403 kb_not_in_allowlist; refused with 403 module_disabled while knowledge bases are switched off on the platform.
Request
Responses
- 201
- 402
- 403
- 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)
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