> ## 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. # Attach a source (idempotent upsert) > The single ingestion endpoint. The server computes the canonical `source_key` and upserts by `(knowledge_base_id, source_key)`: - no existing row → insert, schedule indexing, **201**; - existing row → refresh mutable fields (`fetch_url`, `tags`, `metadata`, `filename`, `mime_type`, `bytes`), schedule a fresh indexing run, **200**. For `native_file_id` sources no fetch URL is stored; storage mints short-lived ones at fetch time. Connector sync = repeat this call per document per cycle with the same `source_url` and a fresh `fetch_url`. Requires `editor`+ on the knowledge base. ## OpenAPI ````yaml /api-reference/storage/swagger.yml post /v1/knowledge_bases/{knowledgeBaseId}/documents 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}/documents: 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: - Documents summary: Attach a source (idempotent upsert) description: | The single ingestion endpoint. The server computes the canonical `source_key` and upserts by `(knowledge_base_id, source_key)`: - no existing row → insert, schedule indexing, **201**; - existing row → refresh mutable fields (`fetch_url`, `tags`, `metadata`, `filename`, `mime_type`, `bytes`), schedule a fresh indexing run, **200**. For `native_file_id` sources no fetch URL is stored; storage mints short-lived ones at fetch time. Connector sync = repeat this call per document per cycle with the same `source_url` and a fresh `fetch_url`. Requires `editor`+ on the knowledge base. operationId: createDocument parameters: - name: agent_id in: query required: false schema: type: string maxLength: 128 description: | Agent context for hook resolution and agent-owned knowledge bases. May also be supplied in the request body. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DocumentCreateRequest' responses: '200': description: Existing document refreshed; indexing rescheduled. content: application/json: schema: $ref: '#/components/schemas/Document' '201': description: New document created; indexing queued. content: application/json: schema: $ref: '#/components/schemas/Document' '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' '503': $ref: '#/components/responses/Error503' security: - BearerAuth: [] - WorkspaceApiKeyAuth: [] components: schemas: DocumentCreateRequest: type: object description: | Body of `POST /documents`. Exactly one source must be identifiable: `native_file_id`, or `source_url`, or `fetch_url` (in dedup-key priority order) - otherwise `400 MISSING_SOURCE`. `source_type` is optional: inferred `uploaded_file` when `native_file_id` is present (a conflicting explicit value is a `400`); defaults to `web_page` for a bare URL. Pass `remote_file` explicitly for non-HTML document bytes at a URL, and `connector_document` from connectors. properties: source_type: type: string enum: - uploaded_file - remote_file - web_page - connector_document native_file_id: type: string description: | Platform-native file id. `404 FILE_NOT_FOUND` if the referenced native file cannot be resolved. Content access is governed by the knowledge base's ACL. Storage resolves `filename`, `mime_type`, `bytes` from the native API unless supplied inline. native_file_workspace_id: type: string description: >- Workspace owning the native file. Defaults to the caller's workspace. source_url: type: string format: uri description: | Stable provenance URL - the dedup key for non-native sources. Defaults to `fetch_url` when omitted. For uploaded files, an optional display override (e.g. a doc viewer page URL). fetch_url: type: string format: uri writeOnly: true description: | Operational URL used to retrieve bytes at index time. May be temporary, signed, tokenized. Write-only - never returned by any response. Ignored for `source_type: uploaded_file` (storage mints its own). Refreshed on every upsert (200 path); connectors send a fresh one on each sync. filename: type: string maxLength: 255 mime_type: type: string bytes: type: integer minimum: 0 chunking_strategy: type: object additionalProperties: true model: type: string maxLength: 256 description: | Optional embedding model override threaded into the indexing pipeline for this document. agent_id: type: string maxLength: 128 description: | Agent context for hook resolution and agent-owned knowledge bases. May also be supplied as the `agent_id` query parameter. scope: type: string enum: - knowledge - conversation default: knowledge conversation_id: type: string expires_at: type: integer description: Unix seconds. tags: type: object additionalProperties: true metadata: type: object additionalProperties: true hooks: type: array writeOnly: true description: | Optional external-hook pass-through (e.g. from agent-factory). Merged with the server-resolved platform/org/agent hook config. A `before_file_ingest` or `after_file_parse` hook may transform or block the content; a block yields `403 HOOK_REJECTED` (sync) or a document in `status: rejected` (async), with `rejection_reason` / `rejected_by` set. Write-only; never returned. items: type: object additionalProperties: true example: source_type: uploaded_file native_file_id: nf_8GkX2p9QwLmZ4rTv1bCdE native_file_workspace_id: wsp_acme tags: conversation_id: conv_42 Document: type: object description: | Association between a source and a knowledge base - the only membership model (no `files` registry). The server computes `source_key` and dedups on `(knowledge_base_id, source_key)`. `fetch_url` is intentionally ABSENT from this schema: it is write-only at the API boundary (may embed credentials). For `source_type: uploaded_file` no fetch URL is stored at all - storage mints a fresh short-lived one (as a privileged workspace) whenever the crawler needs bytes, so expired-token failures are structurally impossible for uploaded files. required: - id - object - knowledge_base_id - source_type - source_key - source_url - origin - status - created_at properties: id: type: string pattern: ^vsf_[A-Za-z0-9-]+$ maxLength: 128 object: type: string enum: - knowledge_base.document knowledge_base_id: type: string pattern: ^vs_[A-Za-z0-9-]+$ source_type: type: string enum: - uploaded_file - remote_file - web_page - connector_document description: | Discriminator. `uploaded_file` for platform-native files (attached by `native_file_id`); `remote_file` for document bytes at an arbitrary URL; `web_page` for HTML pages (single URL or crawl-discovered); `connector_document` for sources owned by a third-party connector. source_key: type: string maxLength: 2048 readOnly: true description: | Server-computed canonical source URI; the dedup key, UNIQUE with `knowledge_base_id`. `prisme-file://{workspace_id}/{native_file_id}` for uploaded files (stable across renames - never the rebuilt native URL); `web://{normalized_url}` otherwise. Normalization is conservative (strip fragment, lowercase scheme + host, normalize percent-encoding, strip default ports - query params untouched) and shared with the crawler's canonicalization. source_url: type: string format: uri description: | User-facing provenance URL - citations, UI links, audit logs. Stable by construction for connector documents (e.g. SharePoint webUrl) and web pages (the page URL). For uploaded files, a display URL (caller-overridable at attach time); downloadable links are minted lazily via `GET /documents/{document_id}/source_url`. native_file_id: type: string description: 'Platform-native file id when `source_type: uploaded_file`.' nullable: true native_file_workspace_id: type: string description: >- Workspace owning the native file. Defaults to the caller's workspace. nullable: true origin: type: string enum: - user - web_source description: | Provenance, set at row creation and never overwritten by seed adoption. Seed deletion cascades only over `origin: web_source` rows - a manually attached page later discovered by a seed keeps `origin: user` and survives the seed's deletion (losing only its `web_source_id`). web_source_id: type: string pattern: ^seed_[A-Za-z0-9-]+$ description: | Primary producing/adopting seed (origin-of-record), when any. Multi-attribution (a page reachable from several seeds) is carried by `parent_web_source_ids`. nullable: true parent_web_source_ids: type: array readOnly: true items: type: string pattern: ^seed_[A-Za-z0-9-]+$ description: | All seeds whose crawl scope covers this page (multi-attribution, §F-5). Backs per-seed page counts and seed cascade-delete: deleting a seed removes it from this array and drops the row only when the array empties AND `origin: web_source`. Empty/absent ⇒ unattributed (counted in the `/web_sources` summary residual). crawler_document_id: type: string description: Crawler-side document id, set once the crawler has seen this source. nullable: true status: type: string enum: - queued - in_progress - completed - failed - fetch_expired - rejected description: | Authoritative indexing status. Transitions are guarded by `index_generation` - stale or duplicate callbacks are ignored. `fetch_expired` is connector-facing: the stored ephemeral `fetch_url` no longer works and the owning connector must refresh it via the upsert (`POST /documents` with the same `source_url`); it is never a user-actionable error and never occurs for `uploaded_file` sources. `rejected` means an external hook (`before_file_ingest` / `after_file_parse`) blocked the content - see `rejection_reason` / `rejected_by`. index_generation: type: integer minimum: 1 readOnly: true description: | Monotonically increasing per document; incremented on every (re)index. Search reads only the latest committed generation; a reindex swaps the new generation in only on success, so the previous good vectors remain searchable on failure. filename: type: string maxLength: 255 nullable: true mime_type: type: string nullable: true bytes: type: integer minimum: 0 nullable: true parser: type: string description: Parser used at last successful parse. nullable: true parsed_at: type: integer nullable: true page_count: type: integer minimum: 0 nullable: true char_count: type: integer minimum: 0 nullable: true chunking_strategy: type: object additionalProperties: true description: Per-document override of the store default. nullable: true scope: type: string enum: - knowledge - conversation default: knowledge conversation_id: type: string nullable: true expires_at: type: integer description: Unix seconds. TTL for conversation-scope documents. nullable: true tags: type: object additionalProperties: true description: Caller-supplied tags. Editable via PATCH. Filterable on list. metadata: type: object additionalProperties: true description: | Connector-supplied structured context (e.g. `connector`, `site_id`, `drive_item_id`, `version`). Editable via PATCH. chunks_count: type: integer minimum: 0 nullable: true vectors_count: type: integer minimum: 0 nullable: true last_error: type: object description: | Most recent failure context. Cleared when a new indexing attempt transitions to `in_progress`. `code: SOURCE_UNAVAILABLE` signals a dangling reference (e.g. the native file was deleted out-of-band - native files emit no lifecycle events, so this surfaces at the next fetch). properties: code: type: string message: type: string details: type: object additionalProperties: true timestamp: type: integer nullable: true errors: type: array readOnly: true description: | Bounded retry/failure history (the most recent failure is also in `last_error`). For debugging repeated index failures. items: type: object properties: code: type: string message: type: string timestamp: type: integer nullable: true message: type: string description: | Human-readable narrative status, distinct from `last_error` (e.g. a partial-success or skipped note). nullable: true failed_at: type: integer description: Unix seconds of the most recent failure. nullable: true rejection_reason: type: string description: | Set when `status: rejected`. Why an external hook blocked the content. Surfaced to the user only when the resolved hook config sets `expose_reason: true`. nullable: true rejected_by: type: string description: Identifier of the hook that produced the rejection. nullable: true indexed_at: type: integer description: Unix seconds. Set when the document reaches `completed`. nullable: true created_at: type: integer updated_at: type: integer example: id: vsf_550e8400-e29b-41d4-a716-446655440000 object: knowledge_base.document knowledge_base_id: vs_7c9e6679-7425-40de-944b-e07fc1f90ae7 source_type: connector_document source_key: >- web://https://contoso.sharepoint.com/sites/x/Shared%20Documents/report.pdf source_url: https://contoso.sharepoint.com/sites/x/Shared%20Documents/report.pdf native_file_id: null native_file_workspace_id: null origin: user web_source_id: null crawler_document_id: crawl_doc_8842 status: completed index_generation: 3 filename: report.pdf mime_type: application/pdf bytes: 234567 parser: tika parsed_at: 1717000000 page_count: 12 char_count: 48213 chunking_strategy: null scope: knowledge conversation_id: null expires_at: null tags: project: contracts-2026 metadata: connector: sharepoint site_id: site_123 drive_item_id: item_456 version: '42' chunks_count: 37 vectors_count: 37 last_error: null indexed_at: 1717000050 created_at: 1714972900 updated_at: 1717000050 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 Error503: description: Storage overloaded or in maintenance. 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. ````