> ## 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. # Semantic Search > Searches a knowledge base and returns ranked chunks. The knowledge base is identified by knowledge_base_id in the body rather than in the path. Results are ranked purely on similarity. Only material whose ingestion has reached 'completed' is searchable. If a recently uploaded document does not appear, check its status before assuming a ranking problem, and use the document chunks endpoint to see what was actually indexed. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/vector/search 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/vector/search: post: tags: - Knowledge Bases summary: Semantic Search description: >- Searches a knowledge base and returns ranked chunks. The knowledge base is identified by knowledge_base_id in the body rather than in the path. Results are ranked purely on similarity. Only material whose ingestion has reached 'completed' is searchable. If a recently uploaded document does not appear, check its status before assuming a ranking problem, and use the document chunks endpoint to see what was actually indexed. operationId: vector_search_api_v1_vector_search_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' responses: '200': description: Ranked chunks. An empty results array means nothing matched. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '401': description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseErrorResponse' '404': description: >- Knowledge base not found, or not owned by your tenant. The two cases are deliberately indistinguishable. 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: SearchRequest: properties: query: type: string title: Query description: The text to search for. knowledge_base_id: type: string title: Knowledge Base Id description: >- The knowledge base to search. Note that this travels in the body, not the path. top_k: type: integer maximum: 100 minimum: 1 title: Top K description: Maximum number of chunks to return, ranked by similarity. default: 5 filter: anyOf: - type: object - type: 'null' title: Filter description: >- Optional metadata filter, passed straight through to the vector backend. Omit it entirely unless you are genuinely filtering: whatever you send becomes a real metadata condition, so leaving an interactive-playground placeholder such as {"additionalProp1": {}} in place will make the search error or silently return nothing. Knowledge-base scoping is applied automatically either way and cannot be bypassed through this field. Only the $eq operator is portable across the supported backends. For example, to match only chunks tagged with a given department, send {"department": {"$eq": "billing"}}. type: object required: - query - knowledge_base_id title: SearchRequest description: Request body for semantic search. example: query: how long do refunds take knowledge_base_id: 1f0a7c3e-9b2d-4c11-8f5a-2e6d9c4b7a01 top_k: 5 SearchResponse: properties: query: type: string title: Query description: The query that was searched, echoed back. results: items: $ref: '#/components/schemas/SearchResult' type: array title: Results description: Matched chunks, ranked by similarity. default: [] type: object required: - query - results title: SearchResponse 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 SearchResult: properties: id: type: string title: Id description: Identifier of the matched chunk. score: type: number title: Score description: Similarity score. Higher is closer. text: type: string title: Text description: The matched chunk text. document_id: type: string title: Document Id description: Identifier of the document this chunk came from. chunk_index: type: integer title: Chunk Index description: Position of this chunk within its document. metadata: type: object title: Metadata description: Metadata stored alongside the chunk at index time. type: object required: - id - score - text title: SearchResult 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 ````