> ## Documentation Index > Fetch the complete documentation index at: https://docs.verbex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Knowledge Base > Creates a knowledge base: a container for documents that AI agents search for context. The embedding model is fixed at creation and cannot be changed afterwards, because changing it would invalidate every vector already stored. Chunking settings can be changed later, but they apply at index time only - material already indexed is never re-chunked. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/knowledge-bases openapi: 3.1.0 info: title: Verbex Platform API description: API for managing AI agents, calls, phone numbers, and more. version: 1.0.0 servers: [] security: [] tags: - name: Knowledge Bases description: >- Create and manage knowledge bases, ingest documents into them, and search them semantically. **Authentication.** Every request carries a bearer token: `Authorization: Bearer `. That is the only credential a client sends. The gateway resolves your identity from it and injects the tenant headers the service reads internally, so clients never send `x-user-org-id` or `x-verbex-id` themselves. **Tenancy is enforced on every route.** A knowledge base belongs to one organization and one user. Requesting one your token does not own returns `404 Knowledge base not found`, never `403`. This is deliberate: a nonexistent ID, a malformed ID and someone else's ID are indistinguishable in the response, so the API cannot be used to probe for other tenants' data. If you get a `404` on an ID you are certain exists, suspect the token before you suspect the ID. **Ingestion is asynchronous.** File upload and website crawl both answer `202` as soon as the material is stored and the job is queued. Parsing, chunking, embedding and indexing happen afterwards in a worker. Poll the document status endpoint until it reports `completed` before expecting search to see the content. That gap is the most common source of "why isn't my data showing up". **There is no document update endpoint.** Every submission mints a new `document_id`, so re-uploading a file or re-crawling the same URLs creates a second document while the first remains. To refresh material, delete then resubmit — and note that the sequence is not atomic. paths: /api/v1/knowledge-bases: post: tags: - Knowledge Bases summary: Create Knowledge Base description: >- Creates a knowledge base: a container for documents that AI agents search for context. The embedding model is fixed at creation and cannot be changed afterwards, because changing it would invalidate every vector already stored. Chunking settings can be changed later, but they apply at index time only - material already indexed is never re-chunked. operationId: create_knowledge_base_api_v1_knowledge_bases_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateKnowledgeBaseRequest' responses: '201': description: Knowledge base created. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseResponse' '401': description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseErrorResponse' '409': description: Integrity conflict, for example concurrent writes to the same key. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '503': description: >- Service unavailable. A database failure, not a problem with your payload. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseErrorResponse' components: schemas: CreateKnowledgeBaseRequest: properties: name: type: string minLength: 1 title: Name description: >- The name of the knowledge base. Should be unique within your organization and clearly identify its purpose. description: type: string title: Description description: >- A description of the knowledge base explaining its contents and purpose. AI agents read this to decide when the knowledge base is relevant. document_language: type: string title: Document Language description: >- Primary language of the material in this knowledge base. Deliberately a free-form string rather than an enum: an unrecognised value is accepted and stored rather than rejected. default: en chunking_strategy: $ref: '#/components/schemas/ChunkingStrategy' description: >- How source material is split before embedding. Applied at index time, so it affects material ingested after it is set. default: recursive vector_backend: $ref: '#/components/schemas/VectorBackendType' description: Vector database backing this knowledge base's index. default: pinecone embedding_model: $ref: '#/components/schemas/EmbeddingModelType' description: >- Embedding model used to vectorise chunks. Immutable: it is accepted here and never on update, because changing it would invalidate every vector already stored. Pick it up front. default: text-embedding-3-large chunk_size: type: integer maximum: 4096 minimum: 100 title: Chunk Size description: >- Target chunk size. Applied at index time; nothing already indexed is re-chunked. default: 512 chunk_overlap: type: integer maximum: 500 minimum: 0 title: Chunk Overlap description: Overlap between consecutive chunks. Applied at index time. default: 50 assistant_persona: anyOf: - type: string maxLength: 280 - type: 'null' title: Assistant Persona description: >- A noun phrase rather than a sentence, describing how an assistant built on this knowledge base introduces itself - for example 'a customer-care voice assistant for Acme Bank'. Defaults to a value derived from the name, capped at 280 characters. Treated as identity-and-tone data in the user message, never as system instructions. It affects only answer generation, a capability this reference does not document, so no endpoint documented here is affected by setting it. type: object required: - name - description title: CreateKnowledgeBaseRequest description: Request body for creating a new knowledge base. example: name: Company Policies description: Knowledge base containing all company policies and procedures document_language: en chunking_strategy: recursive vector_backend: pinecone embedding_model: text-embedding-3-large chunk_size: 512 chunk_overlap: 50 assistant_persona: a customer-care voice assistant for Acme Bank KnowledgeBaseResponse: properties: id: type: string title: Id description: Unique identifier of the knowledge base. name: type: string title: Name description: The name of the knowledge base. description: anyOf: - type: string - type: 'null' title: Description description: Description of the knowledge base's purpose and contents. document_language: type: string title: Document Language description: Primary language of the material in this knowledge base. default: en document_count: type: integer title: Document Count description: Number of documents stored in this knowledge base. default: 0 chunking_strategy: $ref: '#/components/schemas/ChunkingStrategy' description: Chunking strategy currently in effect for new material. default: recursive vector_backend: $ref: '#/components/schemas/VectorBackendType' description: Vector database backing this knowledge base's index. default: pinecone embedding_model: $ref: '#/components/schemas/EmbeddingModelType' description: >- Embedding model in use. Note the asymmetry with the create request, which defaults to text-embedding-3-large: this schema's default is text-embedding-3-small because knowledge bases created before the field existed are on small. Read the value off the response rather than assuming it. default: text-embedding-3-small chunk_size: type: integer title: Chunk Size description: Target chunk size for new material. default: 512 chunk_overlap: type: integer title: Chunk Overlap description: Overlap between consecutive chunks. default: 50 assistant_persona: anyOf: - type: string - type: 'null' title: Assistant Persona description: How an assistant built on this knowledge base introduces itself. status: anyOf: - type: string enum: - processing - completed - failed - type: 'null' title: Status description: Aggregate processing state of the knowledge base's documents. workspace_id: anyOf: - type: string - type: 'null' title: Workspace Id description: Workspace this knowledge base belongs to. organization_id: anyOf: - type: string - type: 'null' title: Organization Id description: >- Organization this knowledge base belongs to, resolved from your token. user_id: anyOf: - type: string - type: 'null' title: User Id description: User this knowledge base belongs to, resolved from your token. created_at: type: string format: date-time title: Created At description: UTC timestamp indicating when this knowledge base was created. updated_at: type: string format: date-time title: Updated At description: UTC timestamp indicating when this knowledge base was last modified. type: object required: - id - name - created_at - updated_at title: KnowledgeBaseResponse description: Response model for a knowledge base. KnowledgeBaseErrorResponse: properties: error: type: string title: Error description: A short error code identifying the type of error that occurred. message: type: string title: Message description: >- A detailed human-readable message explaining the error and possible solutions. type: object required: - error - message title: KnowledgeBaseErrorResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ChunkingStrategy: type: string enum: - fixed_size - semantic - sentence - paragraph - recursive title: ChunkingStrategy description: Strategy used to split source material into chunks before embedding. VectorBackendType: type: string enum: - pinecone - qdrant - weaviate - milvus - pgvector title: VectorBackendType description: Vector database backing the knowledge base's index. EmbeddingModelType: type: string enum: - text-embedding-3-small - text-embedding-3-large title: EmbeddingModelType description: Embedding model used to vectorise chunks. Fixed at creation time. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ````