List documents

curl --request GET \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "object": "list",
  "data": [
    {
      "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
    }
  ],
  "total": 1,
  "page": 2,
  "limit": 50,
  "has_more": true
}

GET

knowledge_bases

{knowledgeBaseId}

documents

List documents

curl --request GET \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "object": "list",
  "data": [
    {
      "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
    }
  ],
  "total": 1,
  "page": 2,
  "limit": 50,
  "has_more": true
}

Authorizations

Authorization

string

header

required

User session JWT or instance API key (iak_*). Send as Authorization: Bearer <token>.

Path Parameters

knowledgeBaseId

string

required

Knowledge base id. Legacy physical prefix vs_ (the kb_ rename is deferred).

Maximum string length: 128

Pattern: ^vs_[A-Za-z0-9-]+$

Query Parameters

limit

integer

default:20

Page size. Server clamps to [1, 100] silently.

Required range: 1 <= x <= 100

page

integer

default:1

1-based page number.

Required range: x >= 1

status

string

One status, or a comma-separated list matched as $in (e.g. ?status=queued,failed - the SPA status multi-select). Values: queued, in_progress, completed, failed, fetch_expired. Connectors use ?status=fetch_expired to discover documents whose ephemeral fetch URL must be refreshed.

source_type

enum<string>

Available options:

uploaded_file,

remote_file,

web_page,

connector_document

origin

enum<string>

Available options:

user,

web_source

web_source_id

string

List pages produced by a seed.

Pattern: ^seed_[A-Za-z0-9-]+$

scope

enum<string>

Available options:

knowledge,

conversation

conversation_id

string

Server-side substring match over the document URL and a denormalized display-text field (ReDoS-guarded). Combinable with the other filters.

Maximum string length: 256

updated_before

integer

Unix-seconds upper bound on updated_at ($lt). For consumer retention sweeps.

agent_id

string

Agent context for agent-owned knowledge bases.

Response

Paginated documents.

Shared list-response envelope. Array is always data. Every element carries its own object discriminator.

object

enum<string>

required

Available options:

list

data

object[]

required

Hide child attributes

data.id

string

required

Maximum string length: 128

Pattern: ^vsf_[A-Za-z0-9-]+$

data.object

enum<string>

required

Available options:

knowledge_base.document

data.knowledge_base_id

string

required

Pattern: ^vs_[A-Za-z0-9-]+$

data.source_type

enum<string>

required

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.

Available options:

uploaded_file,

remote_file,

web_page,

connector_document

data.source_key

string

required

read-only

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.

Maximum string length: 2048

data.source_url

string<uri>

required

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.

data.origin

enum<string>

required

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).

Available options:

user,

web_source

data.status

enum<string>

required

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.

Available options:

queued,

in_progress,

completed,

failed,

fetch_expired,

rejected

data.created_at

integer

required

data.native_file_id

string | null

Platform-native file id when source_type: uploaded_file.

data.native_file_workspace_id

string | null

Workspace owning the native file. Defaults to the caller's workspace.

data.web_source_id

string | null

Primary producing/adopting seed (origin-of-record), when any. Multi-attribution (a page reachable from several seeds) is carried by parent_web_source_ids.

Pattern: ^seed_[A-Za-z0-9-]+$

data.parent_web_source_ids

string[]

read-only

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).

Pattern: ^seed_[A-Za-z0-9-]+$

data.crawler_document_id

string | null

Crawler-side document id, set once the crawler has seen this source.

data.index_generation

integer

read-only

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.

Required range: x >= 1

data.filename

string | null

Maximum string length: 255

data.mime_type

string | null

data.bytes

integer | null

Required range: x >= 0

data.parser

string | null

Parser used at last successful parse.

data.parsed_at

integer | null

data.page_count

integer | null

Required range: x >= 0

data.char_count

integer | null

Required range: x >= 0

data.chunking_strategy

object | null

Per-document override of the store default.

data.scope

enum<string>

default:knowledge

Available options:

knowledge,

conversation

data.conversation_id

string | null

data.expires_at

integer | null

Unix seconds. TTL for conversation-scope documents.

data.tags

object

Caller-supplied tags. Editable via PATCH. Filterable on list.

data.metadata

object

Connector-supplied structured context (e.g. connector, site_id, drive_item_id, version). Editable via PATCH.

data.chunks_count

integer | null

Required range: x >= 0

data.vectors_count

integer | null

Required range: x >= 0

data.last_error

object | null

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).

Hide child attributes

data.last_error.code

string

data.last_error.message

string

data.last_error.details

object

data.last_error.timestamp

integer

data.errors

object[] | null

read-only

Bounded retry/failure history (the most recent failure is also in last_error). For debugging repeated index failures.

Hide child attributes

data.errors.code

string

data.errors.message

string

data.errors.timestamp

integer

data.message

string | null

Human-readable narrative status, distinct from last_error (e.g. a partial-success or skipped note).

data.failed_at

integer | null

Unix seconds of the most recent failure.

data.rejection_reason

string | null

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.

data.rejected_by

string | null

Identifier of the hook that produced the rejection.

data.indexed_at

integer | null

Unix seconds. Set when the document reaches completed.

data.updated_at

integer

total

integer

required

Required range: x >= 0

page

integer

required

Required range: x >= 1

limit

integer

required

Required range: 1 <= x <= 100

has_more

boolean

required

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

Collections API

List documents

Authorizations

Path Parameters

Query Parameters

Response