> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Semantic search > Hits are enriched from document rows directly (no registry join). They carry `document_id` + display `source_url` only - never `fetch_url`, never tokens. Resolve downloadable links lazily via `GET /documents/{document_id}/source_url`. Requires `reader`+. ## OpenAPI ````yaml /api-reference/storage/swagger.yml post /v1/knowledge_bases/{knowledgeBaseId}/search openapi: 3.0.3 info: version: 1.0.0 title: Knowledges API description: > Public REST API for the Prisme.ai Knowledges (storage) workspace: knowledge bases, documents (uploaded files, web pages, remote files, connector documents), recurring web-crawl sources, semantic search, access control, per-knowledge-base API keys, and skills. Resource identifiers use the physical prefixes emitted by the implementation (`vs_` knowledge base, `vsf_` document, `seed_` web source, `kb-` API-key slug). This spec documents the public REST surface only. Internal helpers (private automations prefixed with `_`) and admin/GDPR lifecycle operations are not part of the public contract. contact: name: Prisme.ai url: https://prisme.ai servers: - url: https://{host}/v2/workspaces/slug:storage/webhooks description: Prisme.ai workspace webhooks variables: host: default: api.studio.prisme.ai description: API host (override for self-hosted or sandbox) security: - BearerAuth: [] - WorkspaceApiKeyAuth: [] tags: - name: Knowledge Bases description: >- Create, list, read, update, and delete knowledge bases (vector-backed document stores). - name: Documents description: >- Ingest and manage documents (uploaded files, web pages, remote files, connector documents) and their indexing. - name: Web Sources description: >- Recurring web crawl seeds that discover and index pages into a knowledge base. - name: Search description: Semantic search over a knowledge base. - name: Access description: Per-knowledge-base access bindings (user, group, org, agent principals). - name: API Keys description: Per-knowledge-base API keys for connector authentication. - name: Stats description: Aggregate dashboard statistics. - name: Skills description: Prompt/instruction registry entries. paths: /v1/knowledge_bases/{knowledgeBaseId}/search: parameters: - name: knowledgeBaseId in: path required: true schema: type: string pattern: ^vs_[A-Za-z0-9-]+$ maxLength: 128 description: >- Knowledge base id. Legacy physical prefix `vs_` (the `kb_` rename is deferred). post: tags: - Search summary: Semantic search description: | Hits are enriched from document rows directly (no registry join). They carry `document_id` + display `source_url` only - never `fetch_url`, never tokens. Resolve downloadable links lazily via `GET /documents/{document_id}/source_url`. Requires `reader`+. operationId: searchKnowledgeBase requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string maxLength: 8192 limit: type: integer minimum: 1 maximum: 50 default: 10 min_score: type: number description: Drop hits below this score. filter: $ref: '#/components/schemas/SearchFilter' scope: type: string enum: - knowledge - conversation description: Restrict to a scope. Omit for both. conversation_id: type: string description: 'Required when `scope: conversation`.' responses: '200': description: Search results, best score first. content: application/json: schema: type: object required: - object - data properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/SearchHit' '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '429': $ref: '#/components/responses/Error429' '502': $ref: '#/components/responses/Error502' security: - BearerAuth: [] components: schemas: SearchFilter: type: object description: | Structured filter AST validated at the API boundary; provider adapters transform it into provider DSL internally. Invalid filters are rejected with `400 VALIDATION_ERROR`, never silently coerced. Nesting capped at 8 levels; total leaf clauses at 100. oneOf: - $ref: '#/components/schemas/SearchFilterLeaf' - $ref: '#/components/schemas/SearchFilterAnd' - $ref: '#/components/schemas/SearchFilterOr' - $ref: '#/components/schemas/SearchFilterNot' SearchHit: type: object description: | Single search result, enriched from the document row directly (single row read - no registry join). `source_url` is the display/provenance URL; `fetch_url` and tokens never appear in hits. To obtain a downloadable link (uploaded files), callers resolve `GET /documents/{document_id}/source_url` lazily. required: - document_id - source_type - source_url - score - content properties: document_id: type: string pattern: ^vsf_[A-Za-z0-9-]+$ filename: type: string nullable: true source_type: type: string enum: - uploaded_file - remote_file - web_page - connector_document source_url: type: string format: uri description: | Display/provenance URL for the hit. May be null - some uploaded files carry no display URL, and legacy web rows may have none. `fetch_url` and tokens never appear in hits; obtain a downloadable link lazily via the single (`GET .../documents/{document_id}/source_url`) or batch (`POST .../source_urls`) resolver. nullable: true native_file_id: type: string description: | Platform-native file id when `source_type: uploaded_file`, null otherwise. Pass it (with `native_file_workspace_id`) to the batch or single citation resolver to mint a downloadable link. nullable: true native_file_workspace_id: type: string description: | Workspace owning the native file. Defaults to the caller's workspace; a foreign value means the source can only be resolved from its owning workspace. nullable: true score: type: number content: type: array items: type: object required: - type - text properties: type: type: string enum: - text text: type: string attributes: type: object properties: page: type: integer nullable: true chunk_index: type: integer scope: type: string enum: - knowledge - conversation conversation_id: type: string nullable: true SearchFilterLeaf: type: object required: - op - field - value properties: op: type: string enum: - eq - ne - in - nin - gt - gte - lt - lte - exists - matches field: type: string maxLength: 256 description: | Dot-path filter. **Currently only `tags.` is supported**; `metadata.*`, `source_type`, `web_source_id` and `origin` are not yet implemented and return `400 INVALID_FILTER_FIELD`. value: description: | Operator-dependent. Scalars for `eq`/`ne`/comparisons; arrays for `in`/`nin`; boolean for `exists`; string for `matches`. SearchFilterAnd: type: object required: - and properties: and: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/SearchFilter' SearchFilterOr: type: object required: - or properties: or: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/SearchFilter' SearchFilterNot: type: object required: - not properties: not: $ref: '#/components/schemas/SearchFilter' Error: type: object description: | Single error envelope shared by every non-2xx response. `code` is the stable machine-readable identifier; `message` is the human-readable text; `details` is optional structured context. properties: error: type: object required: - code - message properties: code: type: string example: VALIDATION_ERROR message: type: string details: type: object additionalProperties: true required: - error responses: Error400: description: Caller validation failure. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_source: summary: No identifiable source value: error: code: MISSING_SOURCE message: Provide native_file_id, source_url, or fetch_url. conflicting_type: summary: source_type conflicts with native_file_id value: error: code: VALIDATION_ERROR message: >- source_type must be uploaded_file when native_file_id is provided details: field: source_type Error401: description: Authentication missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthenticated: value: error: code: UNAUTHENTICATED message: Authentication required. Error403: description: Authentication present, authorization denied. content: application/json: schema: $ref: '#/components/schemas/Error' examples: forbidden: value: error: code: FORBIDDEN message: Caller is not allowed to access this resource. hook_rejected: summary: An external content hook blocked ingestion (sync) value: error: code: HOOK_REJECTED message: Content was rejected by a compliance hook. details: rejected_by: hook_pii_filter rejection_reason: detected_unmasked_pii Error404: description: Resource does not exist or is not visible to the caller. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: error: code: NOT_FOUND message: knowledge_base.document not found. details: resource: knowledge_base.document id: vsf_unknown Error429: description: Rate limited. headers: Retry-After: schema: type: integer description: Seconds the caller should wait before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' Error502: description: >- Upstream provider failure (vector DB, LLM gateway, crawler, native files API). content: application/json: schema: $ref: '#/components/schemas/Error' examples: provider_failure: value: error: code: PROVIDER_UNAVAILABLE message: Upstream provider returned an error. details: provider: elasticsearch securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- User session JWT or instance API key (`iak_*`). Send as `Authorization: Bearer `. WorkspaceApiKeyAuth: type: apiKey in: header name: x-prismeai-api-key description: Workspace- or knowledge-base-scoped API key. ````