> ## 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. # List knowledge bases visible to the caller > Scoped by the caller's active `orgSlug` and access bindings. ## OpenAPI ````yaml /api-reference/storage/swagger.yml get /v1/knowledge_bases 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: get: tags: - Knowledge Bases summary: List knowledge bases visible to the caller description: | Scoped by the caller's active `orgSlug` and access bindings. operationId: listKnowledgeBases parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Page' - name: name in: query required: false schema: type: string description: Case-insensitive substring match on `name`. - name: search in: query required: false schema: type: string description: | Case-insensitive substring match on `name` OR `description` (legacy `/vector_stores?search=` parity; takes precedence over `name` when both are sent - added 2026-07-15, SPA migration F1). - name: agent_id in: query required: false schema: type: string - name: scope in: query required: false schema: type: string description: | Comma-separated list of store populations to include - `owned`, `shared`, `all`, `agents`. Defaults to `owned,shared`. `all`/`agents` require the corresponding admin/agent access. - name: status in: query required: false schema: type: string enum: - creating - active - failed - deleting description: | Documented valid values; not strictly server-validated - an unrecognized value yields an empty result rather than a 400. responses: '200': description: Paginated knowledge bases. content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: data: type: array items: $ref: '#/components/schemas/KnowledgeBase' '401': $ref: '#/components/responses/Error401' '429': $ref: '#/components/responses/Error429' security: - BearerAuth: [] components: parameters: Limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Page size. Server clamps to `[1, 100]` silently. Page: name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: 1-based page number. schemas: Pagination: type: object description: | Shared list-response envelope. Array is always `data`. Every element carries its own `object` discriminator. required: - object - data - total - page - limit - has_more properties: object: type: string enum: - list data: type: array items: type: object total: type: integer minimum: 0 page: type: integer minimum: 1 limit: type: integer minimum: 1 maximum: 100 has_more: type: boolean KnowledgeBase: type: object description: | Knowledge base metadata. PATCH is metadata-only; web-crawl configuration lives in `/web_sources`. required: - id - object - name - provider - index_name - embedding - status - owner - owner_org_slug - created_at properties: id: type: string pattern: ^vs_[A-Za-z0-9-]+$ maxLength: 128 object: type: string enum: - knowledge_base name: type: string maxLength: 256 description: type: string maxLength: 4096 provider: type: string enum: - mock - elasticsearch - opensearch - redis - pgvector - qdrant - pinecone index_name: type: string description: Physical index name on the provider. embedding: type: object required: - model - dimensions properties: model: type: string dimensions: type: integer minimum: 1 chunking_strategy: type: object additionalProperties: true description: Default chunking for documents; overridable per document. parser: type: string enum: - tika - tika-ocr - unstructured - unstructured-ocr - llm - null nullable: true file_parsing: type: object properties: image: type: string audio: type: string document: type: string nullable: true status: type: string enum: - creating - active - failed - deleting description: | `creating` before external resources are provisioned; `active` after metadata + physical setup + owner binding succeed; `failed` is a visible failed state with a cleanup-job hook; `deleting` is the transactional deletion window. document_counts: type: object description: | Per-status aggregate over this store's documents. Maintained with transitions guarded by each document's `index_generation` - duplicate or stale crawler callbacks cannot corrupt counters. properties: queued: type: integer minimum: 0 in_progress: type: integer minimum: 0 completed: type: integer minimum: 0 failed: type: integer minimum: 0 fetch_expired: type: integer minimum: 0 total: type: integer minimum: 0 owner: type: object required: - type - id description: | First-class owner principal (§F-6). For agent-owned (conversation-scope) stores `type: agent` and `id` is the agent id - represented as a `principalType: agent` binding in the platform-managed `product_bindings` store, NOT a blanked `owner_user_id`. `owner_user_id` / `agent_id` below mirror this for convenience and filtering. properties: type: type: string enum: - user - agent - org id: type: string maxLength: 128 owner_user_id: type: string description: '`owner.id` when `owner.type == user`; null for agent-owned stores.' nullable: true owner_org_slug: type: string description: Tenant scope. All knowledge-base lookups are scoped by this field. agent_id: type: string description: >- `owner.id` when `owner.type == agent`; null otherwise. Filterable on list. nullable: true role: type: string enum: - owner - admin - editor - reader - null description: | Caller's effective role, computed at read time from access bindings. Null on cross-workspace (`workspace_jwt`) reads. nullable: true access_reason: type: string enum: - owner - admin_binding - editor_binding - reader_binding - agent_binding - trusted_workspace - null nullable: true processing: $ref: '#/components/schemas/Processing' crawl_settings: type: object description: | Engine-global crawl settings - one Crawler instance per KB, so these are the single values the crawler honors (they are NOT per-seed). Read from the store-level columns; edited via the KB PATCH (added 2026-07-17, web-sources crawl-settings re-home). required: - webpages_limit - periodicity - paused properties: webpages_limit: type: integer minimum: 1 description: | Per-crawl page cap, governance-capped (Platform → Org hierarchy). nullable: true periodicity: type: integer description: | Seconds between crawls; null = manual-only (seconds integer rather than an enum for lossless crawler parity - deviation 06-A-1). nullable: true paused: type: boolean description: Whether the whole crawler is paused. max_webpages_limit: type: integer readOnly: true description: | Resolved governance cap (Platform → Org hierarchy) for `webpages_limit` - the "max allowed" hint surfaced on the KB detail response. Read-only; not accepted on PATCH (added 2026-07-20). nullable: true web_source_count: type: integer minimum: 0 description: | Number of registered web sources (crawl seeds). Summary metadata for list cards - the seed objects themselves stay on `/web_sources` (added 2026-07-15, SPA migration F1). last_active_at: type: integer description: Unix seconds. nullable: true created_at: type: integer updated_at: type: integer Processing: type: object description: | Knowledge-base processing / parser-backend health (§F-5). The crawler is the universal parse/fetch backend for EVERY document (uploads, single pages, web crawl), so this is present whenever the knowledge base has documents - even with zero web sources. Live fields come from the crawler; when it is unreachable `crawler_reachable` is false and the live `status`/`metrics` degrade to null rather than erroring (replacing the legacy overloaded `status:"unknown"` + `crawler_error`). DB-derived per-seed counts live on `/web_sources` and remain available regardless. properties: status: type: string enum: - idle - processing - paused - unknown - null nullable: true crawler_reachable: type: boolean description: | `null` by default - the live crawler round-trip only runs when the KB detail request passes `?include=processing`; `true`/ `false` otherwise. nullable: true health: type: object description: | The persisted crawler health - previously exposed by no endpoint, now surfaced here (powers OUT_OF_SPACE / PAUSED inline banners). properties: status: type: string enum: - HEALTHY - OUT_OF_SPACE - PAUSED - UNAUTHENTICATED - UNHEALTHY message: type: string nullable: true last_event_at: type: integer nullable: true metrics: type: object description: Live KB-wide item counts from the crawler; null when unreachable. properties: total_items: type: integer minimum: 0 indexed: type: integer minimum: 0 failed: type: integer minimum: 0 skipped: type: integer minimum: 0 nullable: true last_run_at: type: integer nullable: true 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: Error401: description: Authentication missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthenticated: value: error: code: UNAUTHENTICATED message: Authentication required. 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' 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. ````