> ## 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. # Resolve citation links in a batch > Batch form of the single-doc citation resolver - the N+1 replacement for calling `GET /documents/{document_id}/source_url` once per search hit. Resolves up to 50 documents in one round-trip. Authorization is on the KNOWLEDGE BASE (`reader`+), the same boundary as `/search` and the single-doc resolver: a caller who can search the store already reads its chunks, so a source URL follows the store ACL. Per-item failures are returned INLINE - a document not in this knowledge base, a dangling native file, or a transient mint failure never fails the whole batch, which always returns 200. Each `data` entry is either a resolved `document.source_url` object or a `{ document_id, error }` item; a failed item carries no `object` field, so detect it by the presence of `error`. Technical item failures (`error.technical: true`, e.g. `MINT_FAILED` / `RESOLVE_FAILED`) are retryable; business ones (`NOT_FOUND`, `SOURCE_UNAVAILABLE`) are terminal. ## OpenAPI ````yaml /api-reference/storage/swagger.yml post /v1/knowledge_bases/{knowledgeBaseId}/source_urls 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}/source_urls: 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: Resolve citation links in a batch description: | Batch form of the single-doc citation resolver - the N+1 replacement for calling `GET /documents/{document_id}/source_url` once per search hit. Resolves up to 50 documents in one round-trip. Authorization is on the KNOWLEDGE BASE (`reader`+), the same boundary as `/search` and the single-doc resolver: a caller who can search the store already reads its chunks, so a source URL follows the store ACL. Per-item failures are returned INLINE - a document not in this knowledge base, a dangling native file, or a transient mint failure never fails the whole batch, which always returns 200. Each `data` entry is either a resolved `document.source_url` object or a `{ document_id, error }` item; a failed item carries no `object` field, so detect it by the presence of `error`. Technical item failures (`error.technical: true`, e.g. `MINT_FAILED` / `RESOLVE_FAILED`) are retryable; business ones (`NOT_FOUND`, `SOURCE_UNAVAILABLE`) are terminal. operationId: resolveDocumentSourceUrlsBatch requestBody: required: true content: application/json: schema: type: object required: - document_ids properties: document_ids: type: array minItems: 1 maxItems: 50 items: type: string minLength: 1 maxLength: 128 description: | Document ids to resolve (1-50 per request). Bounded strings, deliberately NOT pattern-constrained to `^vsf_` so legacy or backfilled ids still resolve. knowledge_base_id: type: string maxLength: 128 description: Optional override of the path parameter (body wins). agent_id: type: string maxLength: 128 description: | Agent context for trusted-workspace authorization, used when a trusted product resolves citations on an end user's behalf. responses: '200': description: | One entry per requested document (order not guaranteed). Always 200, even when every item failed - inspect each entry. content: application/json: schema: $ref: '#/components/schemas/BatchSourceUrlResult' '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' '405': $ref: '#/components/responses/Error405' '429': $ref: '#/components/responses/Error429' security: - BearerAuth: [] components: schemas: BatchSourceUrlResult: type: object description: | Batch citation-resolution response. `data` holds one entry per requested document, in no guaranteed order; each entry is either a resolved `document.source_url` object or a per-item error object. Even a fully-failed batch returns 200 - inspect every item. required: - object - data properties: object: type: string enum: - list data: type: array items: oneOf: - $ref: '#/components/schemas/DocumentSourceUrl' - $ref: '#/components/schemas/DocumentSourceUrlErrorItem' DocumentSourceUrl: type: object description: | Result of the lazy citation resolver. For `uploaded_file`, the URL is a short-lived native share URL minted BY THE STORAGE WORKSPACE (not the user - a knowledge-base reader may have no rights on the underlying file; chunk text is already readable through search, so the source follows the knowledge base's ACL). For all other source types, `url` is the document's `source_url` as-is and `expires_at` is null. required: - object - document_id - source_type - url properties: object: type: string enum: - document.source_url document_id: type: string pattern: ^vsf_[A-Za-z0-9-]+$ source_type: type: string enum: - uploaded_file - remote_file - web_page - connector_document url: type: string format: uri expires_at: type: integer description: | Unix seconds. Populated for minted short-lived URLs (`uploaded_file`) and null for every other source type. For a minted URL it is always set: if the file service's own expiry is missing or unparseable, a conservative request-time-plus-TTL estimate is returned rather than null, so callers always have a refresh signal. Re-resolve on expiry. nullable: true DocumentSourceUrlErrorItem: type: object description: | Per-item failure inside a batch source-url response. Deliberately carries NO `object` discriminator (unlike the resolved item), so consumers detect a failed entry by the presence of `error`. An item failure never fails the whole batch - the request still returns 200. required: - document_id - error properties: document_id: type: string error: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND - SOURCE_UNAVAILABLE - MINT_FAILED - RESOLVE_FAILED message: type: string technical: type: boolean description: | Present and true for retryable technical failures (`MINT_FAILED`, `RESOLVE_FAILED`) - the upstream file service errored. Absent for terminal business failures (`NOT_FOUND`, `SOURCE_UNAVAILABLE`). nullable: true details: type: object additionalProperties: 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: 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 Error405: description: Method not allowed on this endpoint. content: application/json: schema: $ref: '#/components/schemas/Error' examples: method_not_allowed: value: error: code: METHOD_NOT_ALLOWED message: Method not allowed 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. ````