> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a knowledge base > Create an empty knowledge base, then add documents to it. Only `name` is required. The rest have defaults, so a minimal request is one field: ```bash theme={"dark"} curl -X POST 'https://api.vocily.ai/v1/knowledge-bases' \ -H 'Authorization: Bearer vk_…' -H 'Content-Type: application/json' \ -d '{ "name": "Pricing FAQ" }' ``` | Field | | | | ------------- | -------------------------------------- | -------------------------------- | | `name` | required | 1-255 characters | | `description` | optional | free text for your own reference | | `language` | `english` \| `multilingual` | defaults to `english` | | `kb_type` | `deterministic` \| `non_deterministic` | defaults to `non_deterministic` | `kb_type` selects how the agent retrieves from it. `non_deterministic` is standard retrieval: the agent synthesises an answer from the matching passages. `deterministic` answers only on a near-exact match and returns the stored text verbatim, which suits content that must not be paraphrased - pricing, policy wording, legal copy. A knowledge base is created empty. Add content with [`POST /v1/knowledge-bases/{kb_id}/documents`](/developers/knowledge-bases/add-document), then attach it to an agent by listing its id in `knowledge_base_ids` on [`PATCH /v1/agents/{agent_id}`](/developers/agents/update). There is no separate attach endpoint: the list is the attachment, so sending it replaces the whole set. ## OpenAPI ````yaml developers/openapi.json POST /v1/knowledge-bases openapi: 3.1.0 info: title: Vocily API description: >- Public REST API for Vocily. Build and configure an agent, publish a version and put it live, place outbound calls, and read back calls, chats and what the agent remembered. Authenticate with a workspace API key as a Bearer token. Some things stay in the dashboard, by design: creating an API key, buying or connecting a phone number, setting an agent's webhook URL, connecting WhatsApp and its templates, building HTTP tools, and running batch campaigns. version: v1 servers: - url: https://api.vocily.ai description: Production security: [] paths: /v1/knowledge-bases: post: tags: - knowledge-bases summary: Create Kb description: Create an empty knowledge base, then add documents to it. operationId: create_kb_v1_knowledge_bases_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicKBCreate' example: name: Support policies description: Refunds, delivery windows and escalation rules. responses: '201': description: The created knowledge base. content: application/json: schema: $ref: '#/components/schemas/PublicKnowledgeBaseRead' example: id: 00000013-0000-4000-8000-000000000013 name: Product FAQ description: >- Pricing pages and the returns policy, kept in sync with the website. language: english kb_type: non_deterministic document_count: 0 created_at: '2026-09-16T19:38:04.356892+00:00' updated_at: '2026-09-16T19:38:04.356892+00:00' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: detail: Invalid API key code: UNAUTHORIZED '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded — honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: rate_limited security: - bearerAuth: [] components: schemas: PublicKBCreate: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: What to call this knowledge base. description: anyOf: - type: string - type: 'null' description: Your own note about what is in it. title: Description language: type: string pattern: ^(english|multilingual)$ title: Language description: '`english` or `multilingual`, matching the content you will upload.' default: english kb_type: type: string pattern: ^(deterministic|non_deterministic)$ title: Kb Type description: >- `non_deterministic` composes an answer from matching passages; `deterministic` answers only on a near-exact match and returns the stored text verbatim — which suits pricing, policy and legal copy that must not be paraphrased. default: non_deterministic additionalProperties: false type: object required: - name title: PublicKBCreate PublicKnowledgeBaseRead: description: >- One knowledge base. `language` and `kb_type` are both growing enums — match on the values you know and fall through on the rest, rather than switching exhaustively. `documents` is returned by get-by-id and is `null` in the list, the same convention as `transcript` on a call. properties: id: description: >- The knowledge base's id. List it in an agent's `knowledge_base_ids` to attach it. title: Id type: string name: description: What it is called. title: Name type: string description: anyOf: - type: string - type: 'null' description: Your own note about what is in it. title: Description language: description: The language its content is in. title: Language type: string kb_type: description: >- How answers are produced: `non_deterministic` composes an answer from matching passages, `deterministic` answers only on a near-exact match and returns the stored text verbatim — which suits pricing, policy and legal copy that must not be paraphrased. title: Kb Type type: string document_count: description: How many documents it holds. title: Document Count type: integer documents: anyOf: - items: $ref: '#/components/schemas/PublicKnowledgeBaseDocumentRead' type: array - type: 'null' default: null description: The documents themselves, with their ingestion status. title: Documents created_at: description: When it was created (UTC, ISO 8601). format: date-time title: Created At type: string updated_at: description: When it last changed (UTC, ISO 8601). format: date-time title: Updated At type: string required: - id - name - description - language - kb_type - document_count - created_at - updated_at title: PublicKnowledgeBaseRead type: object ApiError: type: object description: >- Error envelope. `code` is derived from the HTTP status, so branch on it for the CLASS of failure; the specific reason is `detail.code`. Every public refusal carries both. properties: detail: type: object description: >- The reason. `code` is the domain reason (e.g. `call_not_found`) and `message` is a sentence safe to log. On a `422` it also carries `errors[]`, one entry per rejected field — see `HTTPValidationError`. properties: code: type: string example: call_not_found message: type: string example: Call not found required: - code - message code: type: string description: Derived from the HTTP status, not the domain reason. example: NOT_FOUND HTTPValidationError: type: object title: HTTPValidationError description: >- A request the API could not read: a field of the wrong type, out of range, missing, or one we do not accept. Same envelope as every other error. properties: detail: type: object description: >- What was wrong, as `code`, a one-line `message`, and every offending field in `errors`. required: - code - message - errors properties: code: type: string enum: - validation_error message: type: string description: >- The first problem in one line, with a count of the rest — e.g. `model.temperature: Input should be less than or equal to 2 (and 1 more)`. errors: type: array items: $ref: '#/components/schemas/ValidationError' description: >- One entry per offending field. **Every problem is reported at once**, not just the first, so a malformed body needs one round trip to fix rather than one per field. code: type: string enum: - VALIDATION_ERROR description: Derived from the HTTP status, as on every error. PublicKnowledgeBaseDocumentRead: description: >- One piece of content in a knowledge base, as the public API promises it. `status` is the ingestion state — adding a document returns 202 and processing happens in the background, so a client polls the KB until this reads `processed`. properties: id: description: The document's id. title: Id type: string file_name: anyOf: - type: string - type: 'null' description: The name we stored it under. title: File Name source_url: anyOf: - type: string - type: 'null' description: Where it was fetched from, for a URL-sourced document. title: Source Url mime_type: anyOf: - type: string - type: 'null' description: What kind of file it is. title: Mime Type status: description: >- Where ingestion got to — `pending`, `processing`, `processed`, or `failed`. **Ingestion is asynchronous**: the upload returns `202` and the document is not searchable until this reads `processed`. On `failed`, `error_message` says why. title: Status type: string error_message: anyOf: - type: string - type: 'null' description: Why ingestion failed, if it did. title: Error Message created_at: description: When it was uploaded (UTC, ISO 8601). format: date-time title: Created At type: string updated_at: description: When its status last changed (UTC, ISO 8601). format: date-time title: Updated At type: string required: - id - file_name - source_url - mime_type - status - error_message - created_at - updated_at title: PublicKnowledgeBaseDocumentRead type: object ValidationError: type: object title: ValidationError required: - field - message - type properties: field: type: string description: >- The offending field as a path from the root of your request — `voice.speed`, `variables[0].key`, or `query.limit` for a query parameter. **This is the field to read.** message: type: string description: What is wrong with it, in plain language. type: type: string description: >- A stable machine code for the kind of failure, e.g. `extra_forbidden` for a field we do not accept, `missing` for a required one, or `less_than_equal` for a number out of range. Switch on this rather than on `message`, which may be reworded. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.' ````