> ## Documentation Index > Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt > Use this file to discover all available pages before exploring further. # Search a knowledge base > Run a semantic (vector-similarity) search over a knowledge base and return the matching chunks. For ModuleX-managed (modulexai) knowledge bases this reserves one retrieval credit before the embed/search (reject-before-write), so an exhausted org receives a flat `DenialEnvelope` (402/403/429). BYOK knowledge bases are not billed. Requires the organization admin or owner role. Note: the backend path parameter is `knowledge_base_id`; the nav uses `knowledge_id` (see openQuestions). ## OpenAPI ````yaml /api-reference/openapi.json post /knowledge-bases/{knowledge_id}/search openapi: 3.0.3 info: title: ModuleX API version: 0.1.2 description: >- ModuleX REST API. Authenticate with a user API key (`Authorization: Bearer mx_live_*`, or the `X-API-KEY` header) and supply the organization context header `X-Organization-ID` on org-scoped endpoints. Routers carry NO `/v1` version segment. Billing-gated surfaces (workflow run, managed knowledge search) reject before any write with a flat `DenialEnvelope` (402/403/429). servers: - url: https://api.modulex.dev description: Production security: - bearerAuth: [] orgHeader: [] tags: - name: Workflows description: Create, read, update and delete workflow definitions. - name: Runs description: Execute workflows. Subject to the billing admission gate. - name: Schedules description: Recurring (cron / interval) workflow executions. - name: Knowledge description: Knowledge bases and semantic search. - name: Credentials description: Integration credentials (API key, bearer, OAuth2, ModuleX-managed). - name: Integrations description: Catalog of available tools, LLM providers and knowledge providers. - name: Organizations description: Organization management. - name: API keys description: User-owned API keys for programmatic access. paths: /knowledge-bases/{knowledge_id}/search: parameters: - name: knowledge_id in: path required: true description: Knowledge base UUID. schema: type: string format: uuid post: tags: - Knowledge summary: Search a knowledge base description: >- Run a semantic (vector-similarity) search over a knowledge base and return the matching chunks. For ModuleX-managed (modulexai) knowledge bases this reserves one retrieval credit before the embed/search (reject-before-write), so an exhausted org receives a flat `DenialEnvelope` (402/403/429). BYOK knowledge bases are not billed. Requires the organization admin or owner role. Note: the backend path parameter is `knowledge_base_id`; the nav uses `knowledge_id` (see openQuestions). operationId: searchKnowledgeBase requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' responses: '200': description: Search results. content: application/json: schema: $ref: '#/components/schemas/SearchResult' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/CreditExhausted' '403': $ref: '#/components/responses/QuotaExceeded' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' components: schemas: SearchRequest: type: object required: - query properties: query: type: string minLength: 1 description: Search query. top_k: type: integer default: 5 minimum: 1 maximum: 50 description: Number of results. min_score: type: number format: float default: 0 minimum: 0 maximum: 1 description: Minimum similarity score. filters: type: object additionalProperties: true nullable: true description: Optional metadata filters. include_content: type: boolean default: true description: Include chunk content. include_metadata: type: boolean default: true description: Include chunk metadata. SearchResult: type: object properties: query: type: string knowledge_base_id: type: string format: uuid top_k: type: integer total_matches: type: integer matches: type: array items: type: object additionalProperties: true description: A matching chunk with score and (optionally) content/metadata. Error: type: object description: Standard FastAPI error response. properties: detail: description: >- Human-readable error message, or a structured object (some endpoints return `{message, code, ...}`). oneOf: - type: string - type: object additionalProperties: true DenialEnvelope: type: object description: >- Flat billing/credit/rate/quota denial envelope emitted by the synchronous admission gate (reject-before-write). NO `detail` wrapper. Layer-to-status: `quota`→403, `rate`→429, `credit`/`wallet`→402. required: - code - layer properties: code: type: string description: Machine-stable denial code the client branches on. example: credit_plan_exhausted enum: - credit_plan_exhausted - wallet_overage_disabled - wallet_insufficient - upgrade_payment_failed - quota_exceeded - rate_limit_exceeded layer: type: string description: Which gate layer denied. enum: - rate - quota - credit - wallet key: type: string nullable: true description: >- The specific limit/counter key (e.g. `sync_exec`, `max_knowledge_bases`). current: type: number nullable: true description: Observed usage/count at denial time. limit: type: number nullable: true description: The limit that was hit. reason: type: string nullable: true description: >- Short reason token (e.g. `overage_disabled`, `insufficient_balance`). HTTPValidationError: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationErrorItem' ValidationErrorItem: type: object required: - loc - msg - type properties: loc: type: array items: oneOf: - type: string - type: integer msg: type: string type: type: string responses: Unauthorized: description: >- Authentication required or invalid. Provide `Authorization: Bearer ` or `X-API-KEY`. headers: WWW-Authenticate: schema: type: string description: Bearer content: application/json: schema: $ref: '#/components/schemas/Error' CreditExhausted: description: >- Plan credit allowance exhausted (and no wallet overage available). Flat `DenialEnvelope`, layer `credit`/`wallet`. content: application/json: schema: $ref: '#/components/schemas/DenialEnvelope' example: code: credit_plan_exhausted layer: credit key: null current: 1000 limit: 1000 reason: credit_plan_exhausted QuotaExceeded: description: A per-resource quota was hit. Flat `DenialEnvelope`, layer `quota`. content: application/json: schema: $ref: '#/components/schemas/DenialEnvelope' example: code: quota_exceeded layer: quota key: max_knowledge_bases current: 10 limit: 10 reason: quota_exceeded NotFound: description: The resource was not found (or is not in the caller's organization). content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: Request validation failed (FastAPI 422). content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' RateLimited: description: >- Rate limit exceeded. Flat `DenialEnvelope`, layer `rate`. Includes `Retry-After` and `X-RateLimit-*` headers. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (defaults to 60). X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer description: Unix epoch seconds when the window resets. content: application/json: schema: $ref: '#/components/schemas/DenialEnvelope' example: code: rate_limit_exceeded layer: rate key: sync_exec current: null limit: 60 reason: rate_limit_exceeded securitySchemes: bearerAuth: type: http scheme: bearer description: >- User API key: `Authorization: Bearer mx_live_*`. The `X-API-KEY: mx_live_*` header is also accepted. orgHeader: type: apiKey in: header name: X-Organization-ID description: Required organization context for org-scoped endpoints. ````