Knowledge Base API
Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1> with the intended environment API endpoint and verify that the project and credentials belong to that environment.
Full-chain API for rich-document RAG knowledge bases: knowledge base CRUD, document ingestion (Storage file registration + parse/chunk/Embedding pipeline), chunk-level maintenance, data source connections and synchronization, single-library/cross-library semantic retrieval, index rebuilding, and management observability.
Service and resource boundaries
The KnowledgeBases and Lexicons modules form the core engine of Agentbase platform's enterprise-grade multi-source RAG and query rewriting:
Full-chain RAG lifecycle: covers knowledge base (
{knowledgeBaseId}, e.g.kb_enterprise_support) creation, ingestion from Storage files/external data sources, structured parse and chunking (Chunking), vectorization (e.g. thetext-embedding-v31024-dimension model ofdashscope-prod), single-library/cross-library hybrid retrieval and reranking (qwen3.7-text-rerank).Project-level lexicons: Maintain synonyms, expansions and stopwords, and bind lexicons to a knowledge base or agent workspace. Direct knowledge-base search ignores stopwords; workspace interception requires a binding and
stopInterceptenabled.Derived index and version governance synergy: automatic Wiki compilation on top of knowledge bases, GraphRAG knowledge graphs, and RAPTOR hierarchical clustering indexes are covered in Wiki and Index Governance API; knowledge base immutable version sealing (Seal), publishing (Publish), and rollback are covered in Knowledge Base Version Management API.
Among document location parameters, only creation supports sectionCode; retrieval and listing filter via documentTag and subProductId, and do not accept a standalone sectionCode filter parameter.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/knowledgebases.Hierarchy: knowledge base
{knowledgeBaseId}→ document{documentId}→ chunk{chunkId}; sidecar resources: data source{dataSourceId}, sync{syncId}, ingestion{ingestionId}.Source files are stored in Storage: each knowledge base has a default bucket; when registering a document, reference the
fileIdof an already uploaded file (see storage).
Authentication and Permissions
For authentication and request header conventions, see General Conventions. Scopes in this domain: knowledgebases.read (query, retrieval, management summary), knowledgebases.write (all write operations). Embedding / Rerank are executed via the LLM Gateway (provider reference format project:<providerId> or trial:<bindingId>, see llm-gateway).
Endpoint overview
This page covers two core path prefixes: /v1/knowledgebases (knowledge bases, documents, chunks, ingestion, data sources, and retrieval) and /v1/lexicons (project lexicons, lexicon entries, import/export, rewrite preview, and resource references).
Endpoint List
| Method + path | Purpose |
|---|---|
GET /knowledgebases | List knowledge bases |
POST /knowledgebases | Create knowledge base |
GET /knowledgebases/{knowledgeBaseId} | Get knowledge base |
PATCH /knowledgebases/{knowledgeBaseId} | Update knowledge base |
DELETE /knowledgebases/{knowledgeBaseId} | Delete knowledge base |
POST /knowledgebases/search | Cross-library retrieval (1–10 libraries) |
POST /knowledgebases/{knowledgeBaseId}/search | Single-library retrieval |
GET /knowledgebases/{knowledgeBaseId}/management | Management summary (recent ingestion/trace/scores) |
POST /knowledgebases/{knowledgeBaseId}/reindex | Bounded batch index rebuild |
GET /knowledgebases/{knowledgeBaseId}/documents | List documents |
POST /knowledgebases/{knowledgeBaseId}/documents | Register document; start ingestion separately |
POST /knowledgebases/{knowledgeBaseId}/documents/batch | Batch registration (up to 50 files) |
DELETE /knowledgebases/{knowledgeBaseId}/documents | Batch delete documents (up to 50, atomic precheck) |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId} | Get document |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId} | Update document |
DELETE /knowledgebases/{knowledgeBaseId}/documents/{documentId} | Delete document |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/process | Trigger (re)processing |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/source | Download original source file |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/content | Read document content and truncation status |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact | Get current parse artifact status |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content | Read parsed Markdown |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks | List chunks |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks | Manually create chunk |
GET|PATCH|DELETE .../chunks/{chunkId} | Chunk read/update/delete |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions | Ingestion task list |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions | Start ingestion |
GET|DELETE .../ingestions/{ingestionId} | Ingestion details/cancel |
GET /knowledgebases/{knowledgeBaseId}/datasources | List data sources |
POST /knowledgebases/{knowledgeBaseId}/datasources | Create external data source (Yuque team space) |
GET|PATCH|DELETE .../datasources/{dataSourceId} | Data source read/update/delete |
POST .../datasources/yuque/repos, POST .../datasources/yuque/docs | Enumerate Yuque team repositories and document inventory |
POST .../datasources/{dataSourceId}/documents | Import single document from data source URL |
POST .../datasources/{dataSourceId}/documents/batch | Batch import (up to 20 URLs) |
GET|POST .../datasources/{dataSourceId}/syncs, GET .../syncs/{syncId} | Data source synchronization and status polling |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions | List adoption operations (see version management) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions | Start version adoption (async) (see version management) |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId} | Get adoption operation (see version management) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel | Request adoption cancellation (async) (see version management) |
GET /knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId} | Query version deletion operation (see version management) |
GET /knowledgebases/{knowledgeBaseId}/versions | List versions (see version management) |
POST /knowledgebases/{knowledgeBaseId}/versions | Create working copy (async) (see version management) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId} | Get version (see version management) |
DELETE /knowledgebases/{knowledgeBaseId}/versions/{versionId} | Request irreversible version deletion (async) (see version management) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish | Publish READY version as current version (see version management) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness | Version readiness summary (see version management) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback | Roll back to the retained rollback target (see version management) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal | Seal DRAFT as READY (see version management) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations | List working copy operations (see version management) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId} | Get working copy operation (see version management) |
POST /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel | Request cancellation of working copy operation (see version management) |
GET /lexicons | List project lexicons |
POST /lexicons | Create project lexicon |
GET /lexicons/{lexiconId} | Get lexicon details |
PATCH /lexicons/{lexiconId} | Update lexicon metadata and permissions |
DELETE /lexicons/{lexiconId} | Delete an unbound lexicon |
GET /lexicons/{lexiconId}/entries | List lexicon entries (supports filtering by entryType) |
POST /lexicons/{lexiconId}/entries | Create entry (synonym / expansion / stop) |
GET|PATCH|DELETE /lexicons/{lexiconId}/entries/{entryId} | Entry details/update/delete |
POST /lexicons/{lexiconId}/preview | Preview query rewrite and stopword hit effects |
POST /lexicons/{lexiconId}/import | Batch import entries (JSON / CSV / XLSX, supports dryRun) |
GET /lexicons/{lexiconId}/export | Export lexicon entry file (JSON / CSV / XLSX) |
GET /lexicons/{lexiconId}/references | Query the list of knowledge bases and agents bound to this lexicon |
GET|PUT /knowledgebases/{knowledgeBaseId}/lexicons | Query/wholesale replace the lexicon list bound to a knowledge base |
GET|PUT /agent-runtime/project/lexicons | Query/wholesale replace the lexicon list bound to the current project's agent workspace |
GET|PATCH /knowledgebases/{knowledgeBaseId}/index-capabilities*, POST|GET .../index-operations* | GraphRAG / RAPTOR / LLM Wiki index capability governance and build tasks (see Wiki and Index Governance) |
GET /knowledgebases/{knowledgeBaseId}/graph*, GET|POST .../wiki/* | Knowledge graph, entity neighbors, community reports, and LLM Wiki governance (see Wiki and Index Governance) |
Endpoint details
Lexicon revision number (
revision) and transaction lock: every time an entry is added, deleted, or modified, or a batch import (dryRun=false) is performed, the lexicon master document'srevisionis atomically incremented; when binding a lexicon to a knowledge base or building a GraphRAG index snapshot, the server guarantees entry snapshot consistency via row locks.Entry deduplication and quota limits: a single lexicon can hold at most
1,000entries (LexiconService::MAX_ENTRIES = 1000), with built-indedupeKeyuniqueness validation based on rule type and normalized term; lexicons referenced by knowledge bases or agents cannot be directly deleted before unbinding (returns409 general_conflict).
Requests and Responses
The following sections provide, endpoint by endpoint across resource domains, inputs, outputs, and copyable call/response examples. General conventions:
Authentication: all requests carry
X-Appwrite-Project: <YOUR_PROJECT_ID>andX-Appwrite-Key: <YOUR_API_KEY>; scopeknowledgebases.readcovers query/retrieval/management summary, andknowledgebases.writecovers all write operations.Async tasks (post-registration ingestion
202, reprocessing202, reindex202, data source sync202) must all be polled to a terminal state via the correspondingGETdetails endpoint; ingestion tasks also support RealtimetrackingChannelssubscription.Replace the resource IDs in examples (
kb_product_docs,doc_manual_v2,chk_0042,ds_yuque_team) with actual values.Embedding and reranking are executed via the LLM Gateway, with provider reference format
project:<providerId>ortrial:<bindingId>(see llm-gateway).
Knowledge Base Management
GET /v1/knowledgebases
SDK:KnowledgeBases.list · scope:knowledgebases.read
List all knowledge bases in the current project, searchable by ID/name.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
search | query | string | No | Default "" | Filter by knowledge base ID or name, maximum 256 characters. |
Output:
200, returns model Models.KnowledgeBaseList.
| Field | Type | Description |
|---|---|---|
total* | integer | Total number of knowledge bases matching the query. |
knowledgeBases* | object[] | List of knowledge bases. |
$id* | string | Knowledge base ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
name* | string | Knowledge base name. |
description* | string | Knowledge base description. |
embeddingModel* | string | Embedding model ID pinned at creation time. |
embeddingProviderRef* | string | Pinned Embedding provider source (project:<providerId> / trial:<bindingId>); empty means automatic routing. |
embeddingDimension* | integer | Embedding vector dimension, matching the model output; immutable after creation. |
parserId* | string | Default chunk strategy: general / title / smart / regex / faq. |
parserConfig* | object | Default parsing/chunk configuration (dynamic object; fields are described in the creation endpoint). |
retrievalDefaults* | object | Retrieval defaults (e.g., similarityThreshold, vectorWeight, rate limits). |
vectorsdbDatabaseId* | string | Backing VectorsDB database ID; null before provisioning completes. |
vectorsdbCollectionId* | string | Backing VectorsDB collection ID; null before provisioning completes. |
bucketId* | string | Default Storage bucket ID (where source documents are stored); null before provisioning completes. |
iconFileId* | string | Avatar/icon file ID; null when not set. |
ingestRoutes* | object | Deprecated MIME→Function mapping, kept only for compatibility. |
documentCount* | integer | Total number of documents in the knowledge base. |
Call example:
curl -X GET "https://<your-endpoint>/v1/knowledgebases?search=产品手册" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 2,
"knowledgeBases": [
{
"$id": "kb_product_docs",
"$createdAt": "2026-08-30T09:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:01:12.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 2
}
]
}POST /v1/knowledgebases
SDK:KnowledgeBases.create · scope:knowledgebases.write
Create a knowledge base: pin the Embedding model and automatically provision a dedicated VectorsDB database/collection and Storage bucket.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | body | string | Yes | Knowledge base ID: custom or generated as ID.unique(). | |
name | body | string | Yes | Knowledge base name. | |
description | body | string | No | Knowledge base description. | |
embeddingModel | body | string | Yes | Embedding model ID; the vector dimension is probed once against the LLM Gateway at creation time, and the model and dimension are immutable after creation. | |
embeddingProviderRef | body | string | No | Pin the Embedding provider (project:<providerId> / trial:<bindingId>); omit to use automatic routing. | |
embeddingDimension | body | integer | No | 1–65535 | Explicit vector dimension (2.9.0): validated by probing the selected model; creation fails if it does not match the model output dimension (400). |
tracingEnabled | body | boolean | No | Default false | Ingestion tracing switch (2.9.0): records parsing/chunk intermediate artifacts for use by knowledge base parsing evaluation; depends on a platform administrator global switch, and once enabled, re-ingestion is required for complete evidence. |
parserId (or chunkingStrategy) | body | string | No | Enum: general / title / smart / regex / faq / sheet | Knowledge-base-level default chunking strategy; documents that do not override it are chunked according to this setting. |
parser | body | string | No | Enum: text / mineru / vlm / office | Knowledge-base-level default document parser shorthand (equivalent to parserConfig.documentParser). |
parserConfig | body | object | No | Knowledge-base-level default parsing/chunking and multimodal configuration (subfields below). | |
parserConfig.chunkTokenNum | body | integer | No | Token budget per chunk: general/smart defaults to 512, title/regex defaults to 256; range 64–4096. | |
parserConfig.overlapPercent | body | integer | No | Default 10 | Token overlap percentage between adjacent chunks for the general/smart chunker; defaults to 10 (0–50). |
parserConfig.delimiter | body | string | No | Fallback splitting delimiter for oversized title/regex chunks; defaults to \n。;!? for title and \n。.;;!!?? for regex. | |
parserConfig.titleLevel | body | integer | No | Default 3 | Maximum Markdown heading level split by the title chunker (1–6, default 3, i.e., split down to ###). |
parserConfig.minChunkTokens | body | integer | No | Default 128 | Minimum chunk size for the smart chunker; defaults to 128 and must not exceed chunkTokenNum. |
parserConfig.regexPattern | body | string | No | Default "[.!?]+\\s*" | PCRE regular expression used by the regex chunker; defaults to [.!?]+\s*. |
parserConfig.documentParser | body | string | No | Enum: text / mineru / vlm / office | Document parsing engine: text (plain text/source code parsing), mineru (structured parsing of complex-layout PDFs, tables, and formulas), vlm (full-page parsing by a vision LLM), office (native styles and header extraction for Word/Excel/PPT). |
parserConfig.visionModel | body | string | No | Vision LLM used when documentParser=vlm (e.g., qwen-vl-max). | |
parserConfig.visionProviderRef | body | string | No | Pinned provider reference for the vision model (e.g., project:dashscope-prod). | |
parserConfig.imageUnderstanding (or top-level imageUnderstanding) | body | object | No | Multimodal image understanding configuration: enabled (boolean, whether to enable illustration extraction and semantic transcription), providerRef (string, required, e.g., "project:dashscope-prod"), model (string, required, e.g., "qwen-vl-max"), maxConcurrency (integer, concurrency 1–8, default 4), prompt (string, custom vision understanding prompt), maxImagesPerDocument (integer, image limit per document, default 20), maxDescriptionChars (integer, description character limit per image, default 800). | |
retrievalDefaults | body | object | No | Retrieval defaults (e.g., similarityThreshold, vectorWeight). | |
ingestRoutes | body | object | No | Deprecated MIME→Function mapping, kept only for compatibility. |
Provisioning is asynchronous: vectorsdbDatabaseId / vectorsdbCollectionId / bucketId may briefly be null in the response; re-check with GET shortly after.
Output:
201, returns model Models.KnowledgeBase.
| Field | Type | Description |
|---|---|---|
$id* | string | Knowledge base ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
name* | string | Knowledge base name. |
description* | string | Knowledge base description. |
embeddingModel* | string | Embedding model ID pinned at creation time. |
embeddingProviderRef* | string | Pinned Embedding provider source (project:<providerId> / trial:<bindingId>); empty means automatic routing. |
embeddingDimension* | integer | Embedding vector dimension, matching the model output; immutable after creation. |
parserId* | string | Default chunk strategy: general / title / smart / regex / faq. |
parserConfig* | object | Default parsing/chunk configuration (dynamic object; fields are described in the creation endpoint). |
retrievalDefaults* | object | Retrieval defaults (e.g., similarityThreshold, vectorWeight, rate limits). |
vectorsdbDatabaseId* | string | Backing VectorsDB database ID; null before provisioning completes. |
vectorsdbCollectionId* | string | Backing VectorsDB collection ID; null before provisioning completes. |
bucketId* | string | Default Storage bucket ID (where source documents are stored); null before provisioning completes. |
iconFileId* | string | Avatar/icon file ID; null when not set. |
ingestRoutes* | object | Deprecated MIME→Function mapping, kept only for compatibility. |
documentCount* | integer | Total number of documents in the knowledge base. |
Call example:
curl -X POST "https://<your-endpoint>/v1/knowledgebases" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseId": "kb_product_docs",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"ingestRoutes": {}
}'Response example:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}GET /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.get · scope:knowledgebases.read
Get a knowledge base by ID (including provisioning status and document count).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. |
Output:
200, returns model Models.KnowledgeBase.
| Field | Type | Description |
|---|---|---|
$id* | string | Knowledge base ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
name* | string | Knowledge base name. |
description* | string | Knowledge base description. |
embeddingModel* | string | Embedding model ID pinned at creation time. |
embeddingProviderRef* | string | Pinned Embedding provider source (project:<providerId> / trial:<bindingId>); empty means automatic routing. |
embeddingDimension* | integer | Embedding vector dimension, matching the model output; immutable after creation. |
parserId* | string | Default chunk strategy: general / title / smart / regex / faq. |
parserConfig* | object | Default parsing/chunk configuration (dynamic object; fields are described in the creation endpoint). |
retrievalDefaults* | object | Retrieval defaults (e.g., similarityThreshold, vectorWeight, rate limits). |
vectorsdbDatabaseId* | string | Backing VectorsDB database ID; null before provisioning completes. |
vectorsdbCollectionId* | string | Backing VectorsDB collection ID; null before provisioning completes. |
bucketId* | string | Default Storage bucket ID (where source documents are stored); null before provisioning completes. |
iconFileId* | string | Avatar/icon file ID; null when not set. |
ingestRoutes* | object | Deprecated MIME→Function mapping, kept only for compatibility. |
documentCount* | integer | Total number of documents in the knowledge base. |
Call example:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}PATCH /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.update · scope:knowledgebases.write
Update the knowledge base name, default parsing configuration, or retrieval defaults (only the fields provided are changed).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
name | body | string | No | New name. | |
description | body | string | No | New description. | |
embeddingProviderRef | body | string | No | Pin the Embedding provider; for existing knowledge bases this can be set only once. | |
parserId | body | string | No | Enum: general / title / smart / regex / faq | Knowledge-base-level default chunk strategy. |
parserConfig | body | object | No | Library-level default parsing/chunking configuration (see sub-fields below). | |
parserConfig.chunkTokenNum | body | integer | No | Token budget per chunk: general/smart defaults to 512, title/regex defaults to 256. | |
parserConfig.overlapPercent | body | integer | No | Default 10 | general Token overlap percentage for the chunker, default 10. |
parserConfig.delimiter | body | string | No | Delimiter for over-long title/regex chunks; default is \n。;!? for title and \n。.;;!!?? for regex. | |
parserConfig.titleLevel | body | integer | No | Default 3 | title Markdown heading levels used by the chunker, default 3. |
parserConfig.minChunkTokens | body | integer | No | Default 128 | Minimum chunk size for the smart chunker; defaults to 128 and must not exceed chunkTokenNum. |
parserConfig.regexPattern | body | string | No | Default "[.!?]+\\s*" | regex PCRE expression used by the chunker, default [.!?]+\s*. |
parserConfig.documentParser | body | string | No | Enum: text / vlm / mineru | Document parser: text (plain text) / vlm (vision model) / mineru; MinerU deployment and credentials are outside the scope of this API. |
parserConfig.visionModel | body | string | No | documentParser=vlm The vision model used at that time. | |
parserConfig.visionProviderRef | body | string | No | Pinned provider reference for the vision model. | |
parserConfig.imageUnderstanding | body | object | No | Image interpretation configuration (dynamic object): when enabled=true, model and providerRef are required; also includes prompt, maxImagesPerDocument (default 20), maxDescriptionChars (default 800), maxConcurrency (default 4). | |
retrievalDefaults | body | object | No | Retrieval defaults. | |
ingestRoutes | body | object | No | Deprecated field, kept only for compatibility. | |
iconFileId | body | string | No | File ID of the avatar image (must already be uploaded to this library's default bucket); pass an empty string to clear the avatar. |
Output:
200, returns model Models.KnowledgeBase. embeddingModel and embeddingDimension are fixed after library creation and cannot be modified through this endpoint.
| Field | Type | Description |
|---|---|---|
$id* | string | Knowledge base ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
name* | string | Knowledge base name. |
description* | string | Knowledge base description. |
embeddingModel* | string | Embedding model ID pinned at creation time. |
embeddingProviderRef* | string | Pinned Embedding provider source (project:<providerId> / trial:<bindingId>); empty means automatic routing. |
embeddingDimension* | integer | Embedding vector dimension, matching the model output; immutable after creation. |
parserId* | string | Default chunk strategy: general / title / smart / regex / faq. |
parserConfig* | object | Default parsing/chunk configuration (dynamic object; fields are described in the creation endpoint). |
retrievalDefaults* | object | Retrieval defaults (e.g., similarityThreshold, vectorWeight, rate limits). |
vectorsdbDatabaseId* | string | Backing VectorsDB database ID; null before provisioning completes. |
vectorsdbCollectionId* | string | Backing VectorsDB collection ID; null before provisioning completes. |
bucketId* | string | Default Storage bucket ID (where source documents are stored); null before provisioning completes. |
iconFileId* | string | Avatar/icon file ID; null when not set. |
ingestRoutes* | object | Deprecated MIME→Function mapping, kept only for compatibility. |
documentCount* | integer | Total number of documents in the knowledge base. |
Call example:
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"parserId": "smart",
"parserConfig": {},
"retrievalDefaults": {},
"ingestRoutes": {}
}'Response example:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}DELETE /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.delete · scope:knowledgebases.write
Deletes the knowledge base, cascading deletion of data sources (including sync history), documents, and ingestion records, and asynchronously reclaims VectorsDB resources.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
deleteBucket | body | boolean | No | When true, the default Storage bucket and all files in it are deleted as well; by default the bucket and files are retained. |
Output:
204, no response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"deleteBucket": true
}'GET /v1/knowledgebases/{knowledgeBaseId}/management
SDK:KnowledgeBases.getManagement · scope:knowledgebases.read
Reads a knowledge base's content-agnostic processing and observability summary (recent ingestion, traces, evaluations).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
limit | query | integer | No | Default 10 | Maximum number of entries each of recent ingestion/trace/evaluation includes, default 10. |
from | query | string | No | Default "" | Start of the observability time window (ISO 8601). |
to | query | string | No | Default "" | End of the observability time window (ISO 8601). |
Output:
200, returns a wide-type JSON object (spec does not fix the schema). Typically includes: recent ingestion task summaries (status/phase/duration), retrieval trace summaries, and evaluation records; fields depend on the actual deployment, and an illustrative skeleton is given here.
Call example:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/management?limit=10&from=2026-09-01T00:00:00Z&to=2026-09-14T00:00:00Z" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"recentIngestions": [
{
"$id": "ing_3301",
"documentId": "doc_manual_v2",
"status": "ready",
"stage": "embedding"
}
],
"recentTraces": [
{
"traceId": "4c9f2ab1",
"operation": "search",
"durationMs": 210
}
],
"recentScores": [
{
"documentId": "doc_manual_v2",
"score": 0.91,
"ratedAt": "2026-09-14T08:00:00.000+00:00"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/reindex
SDK:KnowledgeBases.createReindex · scope:knowledgebases.write
Re-enqueues ready documents for ingestion in bounded batches (used to apply changes after updating library-level parsing configuration).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
limit | body | integer | No | Maximum number of ready documents to enqueue in this batch. | |
cursor | body | string | No | Document cursor returned by the previous batch's response. | |
idempotencyKey | body | string | No | Batch idempotency key to prevent duplicate enqueueing. |
Output:
202, returns model Models.KnowledgeBaseReindex; when nextCursor is not null, carry it to call the next batch.
| Field | Type | Description |
|---|---|---|
queued* | integer | Number of ready documents successfully enqueued for re-ingestion in this batch. |
skipped* | integer | Number of documents skipped because an active ingestion already exists. |
failed* | integer | Number of documents that failed to be enqueued in this batch. |
nextCursor* | string | Cursor for the next batch; null indicates all complete. |
Call example:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/reindex" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"limit": 50,
"cursor": "cur_doc_0086",
"idempotencyKey": "idem-reindex-01"
}'Response example:
{
"queued": 12,
"skipped": 0,
"failed": 0,
"nextCursor": null
}Semantic Retrieval
POST /v1/knowledgebases/{knowledgeBaseId}/search
SDK:KnowledgeBases.createSearch · scope:knowledgebases.read
Single-library vector / full-text / hybrid retrieval, optionally reranked via the LLM Gateway, returning chunks with scores and sources.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
query | body | string | Yes | Query text. | |
limit | body | integer | No | Default 10 | Number of results finally returned, range 1–100. |
searchMode | body | string | No | Default hybrid; enum: vector / fulltext / hybrid | Retrieval mode. |
rerank | body | boolean | No | Default false | When true, retrieval is first widened, candidates are reranked via the LLM Gateway, and finally truncated to limit. |
recallLimit | body | integer | No | When rerank is enabled, defaults to min(100, max(limit×4, 20)) if omitted; explicit values 1–100 and must not be less than limit | Retrieval width when rerank is enabled; unused when rerank is off. |
rerankModel | body | string | No | Explicit rerank model ID; overrides automatic selection when rerank is enabled. | |
rerankProviderRef | body | string | No | Pinned rerank provider: project:<providerId> or trial:<bindingId>; do not use the providerType:providerId form. | |
similarityThreshold | body | number | No | Minimum vector similarity threshold (applies to the vector branch of vector and hybrid); omit to use the library's retrievalDefaults.similarityThreshold. | |
vectorWeight | body | number | No | Weight of the vector branch in hybrid mode (full-text gets 1 - vectorWeight); omit to use the library's retrievalDefaults.vectorWeight. | |
useKnowledgeGraph | body | boolean | No | Default false | When true, currently available GraphRAG retrieval results are included. |
useWiki | body | boolean | No | Default false | When true, currently available Wiki retrieval results are included. |
graphOptions | body | object | No | Default {} | Bounded GraphRAG retrieval options; used only when useKnowledgeGraph=true. |
wikiOptions | body | object | No | Default {} | Wiki retrieval options, including routing mode, topK, minK, and vector and bounded link expansion; used only when useWiki=true. |
allowDegraded | body | boolean | No | Default true | Whether, when enhanced retrieval encounters a degradable error, to return ordinary retrieval results and list degradedCapabilities; when set to false, the error is propagated upward. |
answer | body | boolean | No | Default false | Answer synthesis (2.9.0): when true, the chat model from the knowledge base's indexingDefaults performs grounded synthesis of merged evidence (up to 12 lines of evidence, answer ≤1024 tokens), and the response carries a answer object. |
documentTag | body | string | No | Document tags: server 2.12.0 supports multiple non-empty comma-separated tags and segment-aligned matching for chunk, GraphRAG, and Wiki retrieval. | |
subProductId | body | string | No | Sub-product code filter (2.10.0): narrows retrieval by metadata.subProductId first; if absent, falls back to the sub-product segment of the first parseable structured tag with a non-empty sub-product segment; has AND semantics with documentTag. | |
metadataFilter | body | object | No | Document metadata filter (2.10.0): documents are filtered first, then chunks are retrieved; chunks of non-matching documents are excluded. | |
versionId | body | string | No | When omitted, versioned knowledge bases default to the current READY version | Optional version ID; retrieval is executed against the selected version. |
Output:
200, returns model Models.KnowledgeBaseSearchResultList: results[] contains matched chunks, score (rerank score or retrieval score), and optional imageContexts; reranked indicates whether reranking succeeded. This endpoint is subject to both library-level retrievalDefaults.rateLimit/rateLimitPeriod and project rate limits.
| Field | Type | Description |
|---|---|---|
total* | integer | Number of results returned. |
results* | object[] | List of retrieval results. |
$id* | string | Document ID of the matched chunk. |
content* | string | Body text of the matched chunk. |
sourceId* | string | Knowledge base document ID the chunk belongs to. |
source* | object | Description of the source document and protected source URI (dynamic object). |
locator* | object | Section/original-text locator of the chunk (dynamic object). |
metadata* | object | Chunk metadata (internal provenance fields removed). |
imageContexts* | object[] | Association projections of interpreted images within the chunk (response only, does not modify the chunk). |
score* | number | Final ranking score: uses the reranker score if reranking succeeded, otherwise the initial retrieval score. |
indexSource* | string | Result source: rag, raptor, graphrag, or wiki. |
resultType* | string | Result type: chunk, raptor_summary, graph_context, or wiki_page. |
resultGeneration | string / null | Derived index result generation; ordinary RAG chunks are null. |
reranked* | boolean | Whether reranking via the LLM Gateway succeeded; false when automatic rerank failed and degraded. |
resolvedVersionId | string / null | The version actually used for this search; null when versioned reads are not enabled. |
capabilities* | object | Status, elapsed time, result generation, results, and redacted errors for RAPTOR, GraphRAG, and Wiki. |
degradedCapabilities* | object[] | Enhanced capabilities that explicitly degraded; an empty array when no degradation occurred. |
answer | object / null | Answer synthesis result (2.9.0): status / text / model / latency; null when answer synthesis was not requested. |
Call example:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/search" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": "早餐机首次使用要注意什么",
"limit": 5,
"searchMode": "hybrid",
"rerank": false,
"similarityThreshold": 0.5,
"vectorWeight": 0.7
}'Response example:
{
"total": 2,
"results": [
{
"$id": "chk_0042",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
},
"imageContexts": [],
"score": 0.91
},
{
"$id": "chk_0043",
"content": "清洗后首次空烧时若有轻微气味属正常现象,通风放置即可。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 13
},
"metadata": {
"page": 17
},
"imageContexts": [
{
"chunkReferenceIndex": 0,
"url": "/v1/storage/bkt_kb_docs/files/file_img_01/view",
"description": "早餐机正面部件示意图:内胆、蒸汽阀与控制面板位置标注。"
}
],
"score": 0.86
}
],
"reranked": false
}POST /v1/knowledgebases/search
SDK:KnowledgeBases.createMultiSearch · scope:knowledgebases.read
Cross-library retrieval (1–10 libraries): independent retrieval per library → RRF merge → a single unified rerank, returned in global ranking order.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseIds | body | string[] | Yes | Array of knowledge base IDs, 1–10 items with no duplicates. | |
query | body | string | Yes | Query text. | |
limit | body | integer | No | Global TopK (the final number of items after merging all libraries). | |
searchMode | body | string | No | Enum: vector / fulltext / hybrid | Retrieval mode: vector / fulltext / hybrid. |
rerank | body | boolean | No | When true, each library retrieves candidates independently; the server first merges them cross-library via RRF, then performs a single rerank on the merged candidate pool. | |
recallLimit | body | integer | No | Global retrieval width, capped at 100, and must be ≥ limit and ≥ the number of selected knowledge bases. | |
rerankModel | body | string | No | Explicit rerank model ID. | |
rerankProviderRef | body | string | No | Pin the rerank provider (project: / trial: prefix). | |
similarityThreshold | body | number | No | Minimum similarity applied to each library; omit to use each library's default. | |
vectorWeight | body | number | No | Hybrid vector weight applied to each library; omit to use each library's default. | |
documentTag | body | string | No | Document tags: server 2.12.0 supports multiple tags and segment-aligned matching, applied per knowledge base to chunk retrieval. | |
subProductId | body | string | No | Sub-product code filter (2.10.0): narrows the retrieval scope per library. | |
metadataFilter | body | object | No | Document metadata filter (2.10.0): keyed by knowledge base ID, with an optional "*" key as a fallback applied to libraries not individually configured; documents are filtered before retrieval. | |
offset | body | integer | No | 0 | Number of results to skip after fusion ranking (2.10.0), combined with limit for pagination. |
Output:
200, returns model Models.KnowledgeBaseMultiSearchResultList, with each result additionally carrying knowledgeBaseId. Strict failure semantics: if any library does not exist / is not provisioned / is rate-limited / fails retrieval, the entire request fails; on automatic rerank failure, it degrades to RRF order and sets reranked=false. Preflight, retrieval, global rerank, and serialization share a request-level total time limit of 30 seconds; on timeout 408 is returned. Response headers X-RateLimit-Limit/Remaining take the minimum across libraries, X-RateLimit-Reset takes the latest value, and X-AppBase-Trace-Id is the unified correlation ID for this cross-library request.
| Field | Type | Description |
|---|---|---|
total* | integer | Number of results returned. |
results* | object[] | List of results in global ranking order. |
$id* | string | Document ID of the matched chunk. |
knowledgeBaseId* | string | The knowledge base ID containing the chunk; use (knowledgeBaseId, $id) for a cross-library stable identifier. |
content* | string | Body text of the matched chunk. |
sourceId* | string | Knowledge base document ID the chunk belongs to. |
source* | object | Description of the source document and protected source URI (dynamic object). |
locator* | object | Section/original-text locator of the chunk (dynamic object). |
metadata* | object | Chunk metadata (internal provenance fields removed). |
imageContexts* | object[] | Association projections of interpreted images within the chunk (response only, does not modify the chunk). |
score* | number | Final score: the reranker score if global reranking succeeded, otherwise the cross-library RRF score. |
reranked* | boolean | Whether the merged results were successfully reranked once via the LLM Gateway. |
Call example:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/search" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseIds": [
"kb_product_docs",
"kb_faq"
],
"query": "早餐机保修多久",
"limit": 8,
"searchMode": "hybrid",
"rerank": true,
"similarityThreshold": 0,
"vectorWeight": 0
}'Response example:
{
"total": 2,
"results": [
{
"$id": "chk_0042",
"knowledgeBaseId": "kb_product_docs",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
},
"imageContexts": [],
"score": 0.91
},
{
"$id": "chk_faq_007",
"knowledgeBaseId": "kb_faq",
"content": "早餐机整机保修 12 个月,加热元件保修 24 个月。",
"sourceId": "doc_faq_v1",
"source": {
"documentId": "doc_faq_v1",
"uri": "/v1/knowledgebases/kb_faq/documents/doc_faq_v1/source"
},
"locator": {
"generation": "gen_1",
"chapter": 2,
"order": 3
},
"metadata": {},
"imageContexts": [],
"score": 0.84
}
],
"reranked": false
}Document Management
GET /v1/knowledgebases/{knowledgeBaseId}/documents
SDK:KnowledgeBases.listDocuments · scope:knowledgebases.read
Lists documents in a knowledge base; filter by status/stage/enabled or use queries for advanced queries.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | query | string | No | Version ID; when versioning is active, omission selects the current version. | |
status | query | string | No | Default "" | Filter by processing status: uploaded / processing / ready / failed. |
stage | query | string | No | Default "" | Filter by processing stage. |
enabled | query | boolean | No | Filter by enabled state. | |
documentTag | query | string | No | Filter by document tags; server 2.12.0 supports multiple tags and segment-aligned matching. | |
subProductId | query | string | No | Exact filter by sub-product code (2.10.0). | |
directoryPath | query | string | No | Filters by a normalized directory and descendants; a non-empty value cannot be combined with documentTag or subProductId filters. | |
directoryUnclassified | query | boolean | No | Default false | Lists only documents without a directory; true cannot be combined with documentTag or subProductId filters. |
queries | query | string[] | No | Default [] | Array of Appbase Query advanced query strings, at most 100 items with 4096 characters each. When documentTag or subProductId is non-empty, the server ignores queries, including filtering, sorting, and pagination; status, stage, and enabled still apply. |
Directory filter boundaries: A non-empty directoryPath and directoryUnclassified=true are mutually exclusive; directory filters cannot be combined with non-empty documentTag or subProductId. Directory pagination allows Query.limit up to 100; larger values return general_query_invalid.
Output:
200, returns model Models.KnowledgeBaseDocumentList.
| Field | Type | Description |
|---|---|---|
total* | integer | Total number of documents matching the query. |
documents* | object[] | List of documents. |
$id* | string | Document ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Owning knowledge base ID. |
name* | string | Document display name. |
bucketId* | string | Storage bucket ID where the source file resides. |
fileId* | string | Storage file ID of the source file. |
mimeType* | string | MIME type of the source file. |
source* | string | Source: manual manual upload, datasource:{id} data source sync, yuque:personal personal Yuque import. |
externalItemId* | string | External system entry ID, used by data source sync for deduplicated updates. |
parserId* | string | Document-level chunk strategy override; empty means inheriting the library default. |
parserConfig* | object | Document-level parsing/chunking configuration override. |
metadata* | object | Business metadata. |
status* | string | Processing status: uploaded registered / processing processing / ready ready / failed failed. |
enabled* | boolean | Whether the document participates in retrieval; when false, chunks are retained but excluded from retrieval results. |
stage* | string | Mirror of the pipeline stage of the current/most recent ingestion. |
activeIngestionId* | string | ID of the current or most recent ingestion task. |
activeGeneration* | string | Retrieval-visible generation; valid only when status=ready. |
processingStartedAt* | string | Time of the most recent processing trigger. |
chunksTotal* | integer | Expected total number of chunks (populated once known). |
chunkCount* | integer | Number of chunks in the active generation. |
error* | string | Most recent processing error message; normally an empty string. |
lastExecutionId* | string | Deprecated legacy Function execution ID. |
Call example:
The example omits versionId; include the draft version ID as a query parameter when reading a draft.
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents?status=ready&stage=embedding&enabled=true" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 2,
"documents": [
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
},
{
"$id": "doc_faq_v1",
"$createdAt": "2026-09-02T09:00:00.000+00:00",
"$updatedAt": "2026-09-02T09:00:40.000+00:00",
"kbId": "kb_product_docs",
"name": "售后 FAQ.docx",
"bucketId": "bkt_kb_docs",
"fileId": "file_9b22aa",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"source": "manual",
"externalItemId": "",
"parserId": "faq",
"parserConfig": {},
"metadata": {},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3312",
"activeGeneration": "gen_1",
"processingStartedAt": "2026-09-02T09:00:05.000+00:00",
"chunksTotal": 21,
"chunkCount": 21,
"error": "",
"lastExecutionId": ""
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/documents
SDK:KnowledgeBases.createDocument · scope:knowledgebases.write
Registers a file already uploaded to Storage as a document (registration itself does not trigger ingestion; call the ingestion endpoint separately).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
bucketId | body | string | No | Bucket ID where the source file resides; defaults to the library's default bucket if omitted. | |
fileId | body | string | Yes | Storage file ID of the uploaded source file (required). | |
name | body | string | No | Document display name; defaults to the source file name if omitted. | |
source | body | string | No | Document source marker, default manual. | |
externalItemId | body | string | No | Entry ID when originating from an external data source (used for sync deduplication). | |
documentTag | body | string | No | Document tags: server 2.12.0 accepts free-form values and multiple non-empty comma-separated tags. A structured locator may omit its final segment, which the server generates on write; read the stored value for subsequent filtering. | |
subProductId | body | string | No | Sub-product code (2.10.0, 1–64 letters/digits), stored in metadata.subProductId; when a non-empty documentTag is also submitted and this field is omitted or emptied, it is derived only if the first tag is a valid structured locator with a non-empty sub-product segment. A free-form first tag does not guarantee derivation, even when a later tag is structured. Retrieval prefers the standalone field and otherwise falls back to the sub-product segment of the first parseable structured tag with a non-empty sub-product segment. | |
sectionCode | body | string | No | Section code (2.10.0, 1–64 digits); when documentTag is omitted, it is embedded in the automatically generated locator identifier. | |
parserId (or chunkingStrategy) | body | string | No | Enum: general / title / smart / regex / faq / sheet | Document-level chunk strategy override (inherits the knowledge base default strategy when omitted). |
parser | body | string | No | Enum: text / mineru / vlm / office | Document-level parsing engine shorthand override (equivalent to parserConfig.documentParser). |
parserConfig | body | object | No | Document-level parsing/chunking and multimodal configuration override (see sub-fields below). | |
parserConfig.chunkTokenNum | body | integer | No | Token budget per chunk: general/smart defaults to 512, title/regex defaults to 256. | |
parserConfig.overlapPercent | body | integer | No | Default 10 | general/smart Token overlap percentage for the chunker, default 10. |
parserConfig.delimiter | body | string | No | Delimiter for over-long title/regex chunks; default is \n。;!? for title and \n。.;;!!?? for regex. | |
parserConfig.titleLevel | body | integer | No | Default 3 | title Markdown heading levels used by the chunker, default 3. |
parserConfig.minChunkTokens | body | integer | No | Default 128 | Minimum chunk size for the smart chunker; defaults to 128 and must not exceed chunkTokenNum. |
parserConfig.regexPattern | body | string | No | Default "[.!?]+\\s*" | regex PCRE expression used by the chunker, default [.!?]+\s*. |
parserConfig.documentParser | body | string | No | Enum: text / mineru / vlm / office | Document parsing engine: text (plain text) / mineru (MinerU complex layout and table parsing) / vlm (vision large model full-page parsing) / office (Office structured extraction). |
parserConfig.visionModel | body | string | No | documentParser=vlm the vision model used at that time (e.g., qwen-vl-max). | |
parserConfig.visionProviderRef | body | string | No | Pinned provider reference for the vision model (e.g., project:dashscope-prod). | |
parserConfig.imageUnderstanding (or top-level imageUnderstanding) | body | object | No | Multimodal image understanding configuration: enabled (boolean), providerRef (string, e.g. "project:dashscope-prod"), model (string, e.g. "qwen-vl-max"), maxConcurrency (integer, default 4), prompt (string), maxImagesPerDocument (default 20), maxDescriptionChars (default 800). | |
metadata | body | object | No | Business metadata. |
After registration, call POST .../ingestions (or POST .../process) to trigger the parsing → chunk → Embedding pipeline.
Output:
201, returns model Models.KnowledgeBaseDocument (initial status=uploaded).
| Field | Type | Description |
|---|---|---|
$id* | string | Document ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Owning knowledge base ID. |
name* | string | Document display name. |
bucketId* | string | Storage bucket ID where the source file resides. |
fileId* | string | Storage file ID of the source file. |
mimeType* | string | MIME type of the source file. |
source* | string | Source: manual manual upload, datasource:{id} data source sync, yuque:personal personal Yuque import. |
externalItemId* | string | External system entry ID; data source sync uses it for deduplication and updates. |
parserId* | string | Document-level chunk strategy override; empty inherits the knowledge base default. |
parserConfig* | object | Document-level parsing/chunk configuration override. |
metadata* | object | Business metadata. |
status* | string | Processing status: uploaded registered / processing processing / ready ready / failed failed. |
enabled* | boolean | Whether it participates in retrieval; when false, chunks are retained but excluded from retrieval results. |
stage* | string | Mirror of the pipeline stage for the current/most recent ingestion. |
activeIngestionId* | string | ID of the current or most recent ingestion task. |
activeGeneration* | string | Retrieval-visible generation; only valid when status=ready. |
processingStartedAt* | string | Time of the most recent processing trigger. |
chunksTotal* | integer | Expected total number of chunks (filled once known). |
chunkCount* | integer | Number of chunks in the active generation. |
error* | string | Most recent processing error message; normally an empty string. |
lastExecutionId* | string | Deprecated legacy Function execution ID. |
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fileId": "file_9a11cc",
"name": "产品使用手册 v2.pdf",
"source": "ops-console",
"parserId": "smart",
"parserConfig": {},
"metadata": {
"edition": "v2"
}
}' Advanced example of multi-parser and chunk/multimodal image understanding invocation (SIT baseline environment kb_enterprise_support):
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/documents" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"bucketId": "kb_enterprise_docs",
"fileId": "file_ob_arch_v43",
"name": "OceanBase-V4.3-高可用架构白皮书.pdf",
"source": "manual",
"documentTag": "oceanbase_4301_8f9a2b3c4d5e6f708192a3b4c5d6e7f8",
"subProductId": "oceanbase",
"sectionCode": "4301",
"parser": "mineru",
"chunkingStrategy": "smart",
"parserId": "smart",
"parserConfig": {
"documentParser": "mineru",
"chunkTokenNum": 600,
"minChunkTokens": 150,
"overlapPercent": 15,
"imageUnderstanding": {
"enabled": true,
"providerRef": "project:dashscope-prod",
"model": "qwen-vl-max",
"maxConcurrency": 4,
"maxImagesPerDocument": 20,
"maxDescriptionChars": 800,
"prompt": "请提取架构图与故障排查流程图中的核心组件、数据流向与告警阈值,输出结构化文字说明。"
}
},
"imageUnderstanding": {
"enabled": true,
"providerRef": "project:dashscope-prod",
"model": "qwen-vl-max",
"maxConcurrency": 4,
"prompt": "请提取架构图与故障排查流程图中的核心组件、数据流向与告警阈值,输出结构化文字说明。"
},
"metadata": {
"department": "DBA支持中心",
"version": "4.3"
}
}'
)Response example:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents
SDK: KnowledgeBases.deleteDocuments · scope: knowledgebases.write
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Knowledge base ID. |
documentIds | body | string[] | Yes | IDs of 1–50 documents to delete. |
versionId | body | string | When versioning is enabled | Selects a DRAFT version. |
Deletion follows preflight checks and returns 204 on success. Verify the target first; an active versioned knowledge base requires the draft version ID.
POST /v1/knowledgebases/{knowledgeBaseId}/documents/batch
SDK:KnowledgeBases.createDocumentsBatch · scope:knowledgebases.write
Batch-register documents (1–50 files; validate all first, then create).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
fileIds | body | string[] | Yes | Array of Storage file IDs, 1–50 items with no duplicates. | |
bucketId | body | string | No | Bucket containing the files; defaults to the knowledge base default bucket; all files must be in the same bucket. | |
source | body | string | No | Source marker for all documents, default manual. | |
parserId | body | string | No | Enum: general / title / smart / regex / faq | Document-level chunk strategy override (applies to this batch). |
parserConfig | body | object | No | Document-level parsing/chunk configuration override (applies to this batch; see sub-fields below). | |
parserConfig.chunkTokenNum | body | integer | No | Token budget per chunk: general/smart defaults to 512, title/regex defaults to 256. | |
parserConfig.overlapPercent | body | integer | No | Default 10 | general Token overlap percentage for the chunker, default 10. |
parserConfig.delimiter | body | string | No | Delimiter for over-long title/regex chunks; default is \n。;!? for title and \n。.;;!!?? for regex. | |
parserConfig.titleLevel | body | integer | No | Default 3 | title Markdown heading levels used by the chunker, default 3. |
parserConfig.minChunkTokens | body | integer | No | Default 128 | Minimum chunk size for the smart chunker; defaults to 128 and must not exceed chunkTokenNum. |
parserConfig.regexPattern | body | string | No | Default "[.!?]+\\s*" | regex PCRE expression used by the chunker, default [.!?]+\s*. |
parserConfig.documentParser | body | string | No | Enum: text / vlm / mineru | Document parser: text (plain text) / vlm (vision model) / mineru; MinerU deployment and credentials are outside the scope of this API. |
parserConfig.visionModel | body | string | No | documentParser=vlm The vision model used at that time. | |
parserConfig.visionProviderRef | body | string | No | Pinned provider reference for the vision model. | |
parserConfig.imageUnderstanding | body | object | No | Image interpretation configuration (dynamic object): when enabled=true, model and providerRef are required; also includes prompt, maxImagesPerDocument (default 20), maxDescriptionChars (default 800), maxConcurrency (default 4). | |
metadata | body | object | No | Business metadata shared by documents in this batch. |
Output:
201, returns model Models.KnowledgeBaseDocumentList; afterwards ingestion must be initiated per document.
| Field | Type | Description |
|---|---|---|
total* | integer | Total number of documents matching the query. |
documents* | object[] | List of documents. |
$id* | string | Document ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Owning knowledge base ID. |
name* | string | Document display name. |
bucketId* | string | Storage bucket ID where the source file resides. |
fileId* | string | Storage file ID of the source file. |
mimeType* | string | MIME type of the source file. |
source* | string | Source: manual manual upload, datasource:{id} data source sync, yuque:personal personal Yuque import. |
externalItemId* | string | External system entry ID, used by data source sync for deduplicated updates. |
parserId* | string | Document-level chunk strategy override; empty means inheriting the library default. |
parserConfig* | object | Document-level parsing/chunking configuration override. |
metadata* | object | Business metadata. |
status* | string | Processing status: uploaded registered / processing processing / ready ready / failed failed. |
enabled* | boolean | Whether the document participates in retrieval; when false, chunks are retained but excluded from retrieval results. |
stage* | string | Mirror of the pipeline stage of the current/most recent ingestion. |
activeIngestionId* | string | ID of the current or most recent ingestion task. |
activeGeneration* | string | Retrieval-visible generation; valid only when status=ready. |
processingStartedAt* | string | Time of the most recent processing trigger. |
chunksTotal* | integer | Expected total number of chunks (populated once known). |
chunkCount* | integer | Number of chunks in the active generation. |
error* | string | Most recent processing error message; normally an empty string. |
lastExecutionId* | string | Deprecated legacy Function execution ID. |
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/batch" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fileIds": [
"file_9a11cc",
"file_9a12dd"
],
"source": "manual",
"parserId": "smart",
"parserConfig": {},
"metadata": {
"topic": "早餐店经营"
}
}'Response example:
{
"total": 2,
"documents": [
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
},
{
"$id": "doc_faq_v1",
"$createdAt": "2026-09-02T09:00:00.000+00:00",
"$updatedAt": "2026-09-02T09:00:40.000+00:00",
"kbId": "kb_product_docs",
"name": "售后 FAQ.docx",
"bucketId": "bkt_kb_docs",
"fileId": "file_9b22aa",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"source": "manual",
"externalItemId": "",
"parserId": "faq",
"parserConfig": {},
"metadata": {},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3312",
"activeGeneration": "gen_1",
"processingStartedAt": "2026-09-02T09:00:05.000+00:00",
"chunksTotal": 21,
"chunkCount": 21,
"error": "",
"lastExecutionId": ""
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/content
Scope: knowledgebases.read. SDK method availability depends on the published version.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Knowledge base ID. |
documentId | path | string | Yes | Document ID. |
versionId | query | string | No | Knowledge base version ID; the current version is used when omitted for an active versioned knowledge base. |
A successful response returns 200 and a document-content object including content, chunksTotal, truncated, and generation. When truncated is true, the returned content is incomplete. This is distinct from the parse-artifact endpoints.
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}
SDK:KnowledgeBases.getDocument · scope:knowledgebases.read
Get a document by ID (including processing status, generation, and chunk count).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; with versioning enabled, omission reads the current version. Specify the draft ID to read a draft. | |
documentId | path | string | Yes | Target document ID. |
Output:
200, returns model Models.KnowledgeBaseDocument.
| Field | Type | Description |
|---|---|---|
$id* | string | Document ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Owning knowledge base ID. |
name* | string | Document display name. |
bucketId* | string | Storage bucket ID where the source file resides. |
fileId* | string | Storage file ID of the source file. |
mimeType* | string | MIME type of the source file. |
source* | string | Source: manual manual upload, datasource:{id} data source sync, yuque:personal personal Yuque import. |
externalItemId* | string | External system entry ID; data source sync uses it for deduplication and updates. |
parserId* | string | Document-level chunk strategy override; empty inherits the knowledge base default. |
parserConfig* | object | Document-level parsing/chunk configuration override. |
metadata* | object | Business metadata. |
status* | string | Processing status: uploaded registered / processing processing / ready ready / failed failed. |
enabled* | boolean | Whether it participates in retrieval; when false, chunks are retained but excluded from retrieval results. |
stage* | string | Mirror of the pipeline stage for the current/most recent ingestion. |
activeIngestionId* | string | ID of the current or most recent ingestion task. |
activeGeneration* | string | Retrieval-visible generation; only valid when status=ready. |
processingStartedAt* | string | Time of the most recent processing trigger. |
chunksTotal* | integer | Expected total number of chunks (filled once known). |
chunkCount* | integer | Number of chunks in the active generation. |
error* | string | Most recent processing error message; normally an empty string. |
lastExecutionId* | string | Deprecated legacy Function execution ID. |
Call example:
The example omits versionId; include the draft version ID as a query parameter when reading a draft.
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}PATCH /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}
SDK:KnowledgeBases.updateDocument · scope:knowledgebases.write
Update the document name, chunk override configuration, metadata, or enabled status (only fields provided are changed).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
documentId | path | string | Yes | Target document ID. | |
name | body | string | No | Document display name. | |
parserId | body | string | No | Enum: general / title / smart / regex / faq / (empty, meaning no restriction) | Document-level chunk strategy override; passing an empty string clears the override and falls back to the knowledge base default. |
parserConfig | body | object | No | Document-level parsing/chunk configuration override (see sub-fields below). | |
parserConfig.chunkTokenNum | body | integer | No | Token budget per chunk: general/smart defaults to 512, title/regex defaults to 256. | |
parserConfig.overlapPercent | body | integer | No | Default 10 | general Token overlap percentage for the chunker, default 10. |
parserConfig.delimiter | body | string | No | Delimiter for over-long title/regex chunks; default is \n。;!? for title and \n。.;;!!?? for regex. | |
parserConfig.titleLevel | body | integer | No | Default 3 | title Markdown heading levels used by the chunker, default 3. |
parserConfig.minChunkTokens | body | integer | No | Default 128 | Minimum chunk size for the smart chunker; defaults to 128 and must not exceed chunkTokenNum. |
parserConfig.regexPattern | body | string | No | Default "[.!?]+\\s*" | regex PCRE expression used by the chunker, default [.!?]+\s*. |
parserConfig.documentParser | body | string | No | Enum: text / vlm / mineru | Document parser: text (plain text) / vlm (vision model) / mineru; MinerU deployment and credentials are outside the scope of this API. |
parserConfig.visionModel | body | string | No | documentParser=vlm The vision model used at that time. | |
parserConfig.visionProviderRef | body | string | No | Pinned provider reference for the vision model. | |
parserConfig.imageUnderstanding | body | object | No | Image interpretation configuration (dynamic object): when enabled=true, model and providerRef are required; also includes prompt, maxImagesPerDocument (default 20), maxDescriptionChars (default 800), maxConcurrency (default 4). | |
metadata | body | object | No | Business metadata. | |
documentTag | body | string | No | Update the document locator identifier (2.10.0, same format as creation); empty string clears it. | |
subProductId | body | string | No | Update the sub-product code (2.10.0); when a non-empty documentTag is also submitted and this field is omitted or cleared, it is derived only if the first tag is a valid structured locator with a non-empty sub-product segment. A free-form first tag does not guarantee derivation, even when a later tag is structured. When no non-empty label is submitted together with it, an empty string deletes the standalone field, but effective filter values can still fall back to the sub-product segment of the first parseable structured tag with a non-empty sub-product segment; to remove both, clear both fields at the same time. | |
enabled | body | boolean | No | When set to false, the document's chunks are retained but excluded from retrieval results. | |
status | body | string | No | Processing status (legacy correction field, modifiable only via API Key). | |
stage | body | string | No | Processing stage (legacy correction field, modifiable only via API Key). | |
chunksTotal | body | integer | No | Total chunk count (legacy correction field, modifiable only via API Key). | |
chunkCount | body | integer | No | Chunk count (legacy correction field, modifiable only via API Key). | |
error | body | string | No | Error message (legacy correction field, modifiable only via API Key). |
Output:
200, returns model Models.KnowledgeBaseDocument. parserId/parserConfig cannot be changed while an ingestion is queued/running/cancelling.
| Field | Type | Description |
|---|---|---|
$id* | string | Document ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Owning knowledge base ID. |
name* | string | Document display name. |
bucketId* | string | Storage bucket ID where the source file resides. |
fileId* | string | Storage file ID of the source file. |
mimeType* | string | MIME type of the source file. |
source* | string | Source: manual manual upload, datasource:{id} data source sync, yuque:personal personal Yuque import. |
externalItemId* | string | External system entry ID; data source sync uses it for deduplication and updates. |
parserId* | string | Document-level chunk strategy override; empty inherits the knowledge base default. |
parserConfig* | object | Document-level parsing/chunk configuration override. |
metadata* | object | Business metadata. |
status* | string | Processing status: uploaded registered / processing processing / ready ready / failed failed. |
enabled* | boolean | Whether it participates in retrieval; when false, chunks are retained but excluded from retrieval results. |
stage* | string | Mirror of the pipeline stage for the current/most recent ingestion. |
activeIngestionId* | string | ID of the current or most recent ingestion task. |
activeGeneration* | string | Retrieval-visible generation; only valid when status=ready. |
processingStartedAt* | string | Time of the most recent processing trigger. |
chunksTotal* | integer | Expected total number of chunks (filled once known). |
chunkCount* | integer | Number of chunks in the active generation. |
error* | string | Most recent processing error message; normally an empty string. |
lastExecutionId* | string | Deprecated legacy Function execution ID. |
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "产品使用手册 v2.pdf",
"parserId": "general",
"parserConfig": {},
"metadata": {
"topic": "早餐店经营"
},
"enabled": true,
"chunksTotal": 0,
"chunkCount": 0
}'Response example:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}
SDK:KnowledgeBases.deleteDocument · scope:knowledgebases.write
Delete the document: cascades deletion of all its chunks (VectorsDB), ingestion records, and decrements the knowledge base document count.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
documentId | path | string | Yes | Target document ID. |
Output:
204, no response body.
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"POST /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/process
SDK:KnowledgeBases.createDocumentProcess · scope:knowledgebases.write
Trigger one (re)processing run of an existing document with its current configuration, equivalent to creating an ingestion with default parameters.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
documentId | path | string | Yes | Target document ID. |
Output:
202, returns model Models.KnowledgeBaseIngestion. Asynchronous task: poll GET .../ingestions/{ingestionId} until a terminal state (ready / failed / cancelled), or subscribe to the Realtime channel in trackingChannels of the response.
| Field | Type | Description |
|---|---|---|
$id* | string | Ingestion task ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Knowledge base ID. |
documentId* | string | Document ID. |
status* | string | Task status: queued / running / ready / failed / cancelling / cancelled. |
stage* | string | Current pipeline stage (parsing → chunk → Embedding). |
generation* | string | Generation written by this ingestion. |
progress* | object | Progress object: completed / total / unit. |
effectiveConfig* | object | Snapshot of the configuration frozen in effect for this ingestion. |
configHash* | string | effectiveConfig hash, used to compare whether the configuration has changed. |
retryOf* | string | Previous ingestion ID pointed to on retry. |
attemptId* | string | Fencing token for this attempt. |
idempotencyKey* | string | Requester's idempotency key. |
error* | string | Error message when failed. |
startedAt* | string | Time the worker started processing. |
finishedAt* | string | Ingestion end time. |
trackingChannels* | object | Realtime subscription channels: ingestion (this task) and document (parent document). |
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/process" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "running",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 60,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/source
SDK:KnowledgeBases.getDocumentSource · scope:knowledgebases.read
Download the original source file of the document (binary stream, not JSON).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; with versioning enabled, omission reads the current version. Specify the draft ID to read a draft. | |
documentId | path | string | Yes | Target document ID. |
Save the file with -o; do not parse it as JSON.
Output:
200, File binary content (Content-Type is the source file's MIME type), for archiving or manual verification.
Call example:
The example omits versionId; include the draft version ID as a query parameter when reading a draft.
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Chunks
Tag matching boundaries: 2.12.0 uses underscore-delimited segment prefixes for both structured and free-form tags: finance can match finance_confidential_notes. Removing trailing empty segments from ___ can match documents with tags; avoid all-underscore filters. This filter is not an authorization boundary. Effective subProductId resolution skips free-form tags and structured tags with an empty sub-product segment; for example, _12_<fileKey> followed by ob_12_<fileKey> can resolve to ob. An explicit field takes precedence.
Read a document parse artifact
Both REST endpoints require knowledgebases.read; availability of SDK methods depends on the published artifact. A parse artifact is Markdown produced before chunking, not a chunk list.
Get artifact status
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Knowledge base ID. |
documentId | path | string | Yes | Document ID. |
versionId | query | string | No | Selects a knowledge base version; when version management is active, omission uses the current version. |
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS "${APPBASE_ENDPOINT:?Set endpoint including /v1}/knowledgebases/${KB_ID:?Set KB_ID}/documents/${DOCUMENT_ID:?Set DOCUMENT_ID}/parse-artifact" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID:?Set project ID}"
)A successful request returns 200; byteSize and sha256 below are illustrative:
{
"knowledgeBaseId": "kb_example",
"documentId": "doc_example",
"status": "ready",
"supported": true,
"generation": "gen_1",
"byteSize": 36,
"sha256": "81968d11f4746b211ad5eed0cb1a6e732a2da734b2ff2a6754ce52c31149d45e"
}status can be not_generated, ready, or too_large; an artifact from a non-active generation is reported as not_generated. For a successfully loaded document, this version always returns supported: true; it does not establish whether the document or parser has produced an artifact. Use status, the active generation, and the content endpoint to determine availability. generation, byteSize, and sha256 can be null when unavailable.
Read artifact content
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content accepts the same path parameters and optional versionId query parameter.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS "${APPBASE_ENDPOINT:?Set endpoint including /v1}/knowledgebases/${KB_ID:?Set KB_ID}/documents/${DOCUMENT_ID:?Set DOCUMENT_ID}/parse-artifact/content" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID:?Set project ID}"
)200 returns text/markdown; charset=utf-8. Check status before calling the content endpoint:
| HTTP status | Error type | Meaning |
|---|---|---|
400 | general_argument_invalid | The artifact was too large to store. |
404 | storage_file_not_found | The artifact was not generated or no longer belongs to the active generation; re-ingest if needed and check again. |
Missing knowledge bases, documents, or versions and insufficient permissions can return their respective errors; inspect the actual error type.
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks
SDK:KnowledgeBases.listChunks · scope:knowledgebases.read
List chunks of the document's currently active generation, supporting keyword search and advanced queries over content.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; with versioning enabled, omission reads the current version. Specify the draft ID to read a draft. | |
documentId | path | string | Yes | Target document ID. | |
search | query | string | No | Default "" | Keyword search within chunk body text. |
queries | query | string[] | No | Default [] | Array of Appbase Query advanced query strings, up to 100 items. |
Output:
200, returns model Models.KnowledgeBaseChunkList.
| Field | Type | Description |
|---|---|---|
total* | integer | Total number of chunks matching the query. |
chunks* | object[] | List of chunks. |
$id* | string | Chunk ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
documentId* | string | Owning document ID. |
content* | string | Chunk body text. |
ingestVersion* | string | Ingestion generation the chunk belongs to. |
source* | object | Authoritative source document description and protected source URI (dynamic object). |
locator* | object | Versioned section and source text locators (dynamic object). |
metadata* | object | Chunk metadata, with internal provenance fields stripped. |
Call example:
The example omits versionId; include the draft version ID as a query parameter when reading a draft.
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks?search=首次使用" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 2,
"chunks": [
{
"$id": "chk_0042",
"$createdAt": "2026-09-01T08:00:31.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"documentId": "doc_manual_v2",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
}
},
{
"$id": "chk_0043",
"$createdAt": "2026-09-01T08:00:31.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"documentId": "doc_manual_v2",
"content": "清洗后首次空烧时若有轻微气味属正常现象,通风放置即可。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 13
},
"metadata": {
"page": 17
}
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks
SDK:KnowledgeBases.createChunk · scope:knowledgebases.write
Manually create chunks for a document directly, bypassing the parsing pipeline (embeddings are computed by the LLM Gateway).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
documentId | path | string | Yes | Target document ID. | |
content | body | string | Yes | Chunk body text (required). | |
metadata | body | object | No | Arbitrary chunk metadata. |
Output:
201, returning model Models.KnowledgeBaseChunk; the document's chunkCount/chunksTotal increment accordingly. The document must already have an active generation (i.e., ingestion has been completed at least once).
| Field | Type | Description |
|---|---|---|
$id* | string | Chunk ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
documentId* | string | Owning document ID. |
content* | string | Chunk body text. |
ingestVersion* | string | Ingestion generation the chunk belongs to. |
source* | object | Authoritative source document description and protected source URI (dynamic object). |
locator* | object | Versioned section and source text locators (dynamic object). |
metadata* | object | Chunk metadata, with internal provenance fields stripped. |
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"content": "保修政策:自购买之日起整机保修 12 个月。",
"metadata": {
"section": "售后"
}
}'Response example:
{
"$id": "chk_0042",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"documentId": "doc_manual_v2",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
}
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
SDK:KnowledgeBases.getChunk · scope:knowledgebases.read
Get a single chunk by ID.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; with versioning enabled, omission reads the current version. Specify the draft ID to read a draft. | |
documentId | path | string | Yes | Target document ID. | |
chunkId | path | string | Yes | Target chunk ID. |
Output:
200, returns model Models.KnowledgeBaseChunk.
| Field | Type | Description |
|---|---|---|
$id* | string | Chunk ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
documentId* | string | Owning document ID. |
content* | string | Chunk body text. |
ingestVersion* | string | Ingestion generation the chunk belongs to. |
source* | object | Authoritative source document description and protected source URI (dynamic object). |
locator* | object | Versioned section and source text locators (dynamic object). |
metadata* | object | Chunk metadata, with internal provenance fields stripped. |
Call example:
The example omits versionId; include the draft version ID as a query parameter when reading a draft.
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks/chk_0042" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "chk_0042",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"documentId": "doc_manual_v2",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
}
}PATCH /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
SDK:KnowledgeBases.updateChunk · scope:knowledgebases.write
Update a chunk's content, metadata, or retrieval enablement. Changing content (or image description metadata) recomputes the vector. A disabled chunk is excluded from knowledge base search and remains disabled across document publications. Re-enabling it permits retrieval only when the document, ingestion generation, and version publication state allow it. This describes the REST API; enabled support in an SDK depends on the SDK version.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
documentId | path | string | Yes | Target document ID. | |
chunkId | path | string | Yes | Target chunk ID. | |
content | body | string | No | New body text; providing it triggers vector recomputation (along with persisted image descriptions). | |
metadata | body | object | No | Chunk metadata; vectors are recomputed only when image descriptions change. | |
enabled | body | boolean | No | Whether the chunk may participate in retrieval; omit to leave unchanged. | |
versionId | body | string | No | DRAFT version ID is required for writes when versioning is active. |
Output:
200, returns model Models.KnowledgeBaseChunk.
| Field | Type | Description |
|---|---|---|
$id* | string | Chunk ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
documentId* | string | Owning document ID. |
content* | string | Chunk body text. |
ingestVersion* | string | Ingestion generation the chunk belongs to. |
enabled | boolean | Whether the chunk may participate in retrieval. |
source* | object | Authoritative source document description and protected source URI (dynamic object). |
locator* | object | Versioned section and source text locators (dynamic object). |
metadata* | object | Chunk metadata, with internal provenance fields stripped. |
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks/chk_0042" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"content": "Warranty lasts 24 months from purchase.",
"enabled": false,
"metadata": {
"topic": "warranty"
}
}'
)Response example:
{
"$id": "chk_0042",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"documentId": "doc_manual_v2",
"content": "Warranty lasts 24 months from purchase.",
"enabled": false,
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"topic": "warranty"
}
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
SDK:KnowledgeBases.deleteChunk · scope:knowledgebases.write
Delete a single chunk; the parent document's chunkCount/chunksTotal decrease accordingly.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
documentId | path | string | Yes | Target document ID. | |
chunkId | path | string | Yes | Target chunk ID. |
Output:
204, no response body.
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks/chk_0042" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Ingestion
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions
SDK:KnowledgeBases.listIngestions · scope:knowledgebases.read
List the ingestion task history of a document; filter and sort with queries.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; with versioning enabled, omission reads the current version. Specify the draft ID to read a draft. | |
documentId | path | string | Yes | Target document ID. | |
queries | query | string[] | No | Default [] | Array of Appbase Query advanced query strings, up to 100 items. |
Output:
200, returns model Models.KnowledgeBaseIngestionList.
| Field | Type | Description |
|---|---|---|
total* | integer | Total number of ingestion tasks matching the query. |
ingestions* | object[] | List of ingestion tasks. |
$id* | string | Ingestion task ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Knowledge base ID. |
documentId* | string | Document ID. |
status* | string | Task status: queued / running / ready / failed / cancelling / cancelled. |
stage* | string | Current pipeline stage (parse → chunk → Embedding). |
generation* | string | Generation written by this ingestion. |
progress* | object | Progress object: completed / total / unit. |
effectiveConfig* | object | Snapshot of configuration frozen and applied for this ingestion. |
configHash* | string | Hash of effectiveConfig, used to detect configuration changes. |
retryOf* | string | Previous ingestion ID referenced when retrying. |
attemptId* | string | Fencing token for this attempt. |
idempotencyKey* | string | Requester's idempotency key. |
error* | string | Error message when failed. |
startedAt* | string | Time the worker started processing. |
finishedAt* | string | Ingestion end time. |
trackingChannels* | object | Realtime subscription channels: ingestion (this task) and document (parent document). |
Call example:
The example omits versionId; include the draft version ID as a query parameter when reading a draft.
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/ingestions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 2,
"ingestions": [
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "ready",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 86,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "2026-09-01T08:00:31.000+00:00",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions
SDK:KnowledgeBases.createIngestion · scope:knowledgebases.write
Trigger an ingestion for a document (parse → chunk → Embedding); 202 executes asynchronously.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
documentId | path | string | Yes | Target document ID. | |
idempotencyKey | body | string | No | Idempotency key: retrying with the same key returns the existing ingestion instead of enqueueing a duplicate. | |
retryOf | body | string | No | ID of a previous failed ingestion to retry. | |
persistToDocument | body | boolean | No | When true, the overrides for this ingestion are promoted to document-level configuration after ingestion completes. | |
overrides | body | object | No | Parsing overrides effective only for this ingestion; embedding-related fields are rejected (see subfields below). | |
overrides.parserId | body | string | No | Enum: general / title / smart / regex / faq | Chunking strategy override for this ingestion. |
overrides.parserConfig | body | object | No | Parse/chunk configuration overrides effective only for this ingestion; subfields are the same as parserConfig (see the knowledge base creation endpoint); embedding fields are rejected. |
Output:
202, returning model Models.KnowledgeBaseIngestion (initial status=queued). Polling approach : GET .../ingestions/{ingestionId} every 2–3 seconds, status until a terminal state of ready/failed/cancelled is reached; alternatively, subscribe to the trackingChannels channel for real-time progress.
| Field | Type | Description |
|---|---|---|
$id* | string | Ingestion task ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Knowledge base ID. |
documentId* | string | Document ID. |
status* | string | Task status: queued / running / ready / failed / cancelling / cancelled. |
stage* | string | Current pipeline stage (parsing → chunk → Embedding). |
generation* | string | Generation written by this ingestion. |
progress* | object | Progress object: completed / total / unit. |
effectiveConfig* | object | Snapshot of the configuration frozen in effect for this ingestion. |
configHash* | string | effectiveConfig hash, used to compare whether the configuration has changed. |
retryOf* | string | Previous ingestion ID pointed to on retry. |
attemptId* | string | Fencing token for this attempt. |
idempotencyKey* | string | Requester's idempotency key. |
error* | string | Error message when failed. |
startedAt* | string | Time the worker started processing. |
finishedAt* | string | Ingestion end time. |
trackingChannels* | object | Realtime subscription channels: ingestion (this task) and document (parent document). |
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/ingestions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "idem-ingest-01",
"retryOf": "ing_3298",
"persistToDocument": false,
"overrides": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 384
}
}
}'Response example:
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "running",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 60,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions/{ingestionId}
SDK:KnowledgeBases.getIngestion · scope:knowledgebases.read
Query the status, stage, progress, and errors of a single ingestion task.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; with versioning enabled, omission reads the current version. Specify the draft ID to read a draft. | |
documentId | path | string | Yes | Target document ID. | |
ingestionId | path | string | Yes | Target ingestion task ID. |
Output:
200, returning model Models.KnowledgeBaseIngestion (the polling entry point for async tasks, including Realtime trackingChannels).
| Field | Type | Description |
|---|---|---|
$id* | string | Ingestion task ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Knowledge base ID. |
documentId* | string | Document ID. |
status* | string | Task status: queued / running / ready / failed / cancelling / cancelled. |
stage* | string | Current pipeline stage (parsing → chunk → Embedding). |
generation* | string | Generation written by this ingestion. |
progress* | object | Progress object: completed / total / unit. |
effectiveConfig* | object | Snapshot of the configuration frozen in effect for this ingestion. |
configHash* | string | effectiveConfig hash, used to compare whether the configuration has changed. |
retryOf* | string | Previous ingestion ID pointed to on retry. |
attemptId* | string | Fencing token for this attempt. |
idempotencyKey* | string | Requester's idempotency key. |
error* | string | Error message when failed. |
startedAt* | string | Time the worker started processing. |
finishedAt* | string | Ingestion end time. |
trackingChannels* | object | Realtime subscription channels: ingestion (this task) and document (parent document). |
Call example:
The example omits versionId; include the draft version ID as a query parameter when reading a draft.
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/ingestions/ing_3301" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "running",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 60,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions/{ingestionId}
SDK:KnowledgeBases.deleteIngestion · scope:knowledgebases.write
Cancel an ingestion: queued/running tasks transition to cancelling; tasks in a terminal state remain unchanged (idempotent).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required for writes when versioning is enabled; specify a DRAFT version ID. | |
documentId | path | string | Yes | Target document ID. | |
ingestionId | path | string | Yes | Target ingestion task ID. |
Output:
202, returning model Models.KnowledgeBaseIngestion (current status); this operation does not delete the record.
| Field | Type | Description |
|---|---|---|
$id* | string | Ingestion task ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Knowledge base ID. |
documentId* | string | Document ID. |
status* | string | Task status: queued / running / ready / failed / cancelling / cancelled. |
stage* | string | Current pipeline stage (parsing → chunk → Embedding). |
generation* | string | Generation written by this ingestion. |
progress* | object | Progress object: completed / total / unit. |
effectiveConfig* | object | Snapshot of the configuration frozen in effect for this ingestion. |
configHash* | string | effectiveConfig hash, used to compare whether the configuration has changed. |
retryOf* | string | Previous ingestion ID pointed to on retry. |
attemptId* | string | Fencing token for this attempt. |
idempotencyKey* | string | Requester's idempotency key. |
error* | string | Error message when failed. |
startedAt* | string | Time the worker started processing. |
finishedAt* | string | Ingestion end time. |
trackingChannels* | object | Realtime subscription channels: ingestion (this task) and document (parent document). |
Call example:
The example omits versionId and applies when versioning is disabled; when enabled, include a DRAFT version ID in the request body.
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/ingestions/ing_3301" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "cancelling",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 60,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}Data Sources and Sync
GET /v1/knowledgebases/{knowledgeBaseId}/datasources
SDK:KnowledgeBases.listDataSources · scope:knowledgebases.read
List the data sources connected to a knowledge base; filter by type/status.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | query | string | No | Optional; defaults to the current ready version when versioning is enabled. | |
type | query | string | No | Default "" | Filter by data source type (currently yuque). |
status | query | string | No | Default "" | Filter by status: active / disabled / error. |
Output:
200, returns model Models.KnowledgeBaseDataSourceList.
| Field | Type | Description |
|---|---|---|
total* | integer | Total number of data sources matching the query. |
dataSources* | object[] | List of data sources. |
$id* | string | Data source ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Bound knowledge base ID. |
type* | string | Data source type (current enum: yuque). |
name* | string | Data source name. |
config* | object | Non-sensitive configuration (e.g., repoNamespaces, syncSchedule). |
credentials* | object | Credential metadata; secrets are never echoed back. |
status* | string | Status: active / disabled / error. |
lastSyncAt* | string | Time the most recent sync completed. |
lastSyncStatus* | string | Status of the most recent sync. |
lastCursor* | string | Incremental sync cursor. |
error* | string | Most recent data source error message. |
Call example:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources?type=yuque&status=active" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 2,
"dataSources": [
{
"$id": "ds_yuque_team",
"$createdAt": "2026-08-30T10:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:01:12.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "team-docs",
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {"teamToken": "********"},
"status": "active",
"lastSyncAt": "2026-09-14T02:01:12.000+00:00",
"lastSyncStatus": "ready",
"lastCursor": "yq-2026-09-14T02:00:00Z",
"error": ""
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources
SDK:KnowledgeBases.createDataSource · scope:knowledgebases.write
Connect an external data source to a knowledge base (currently supports Yuque team spaces), with optional registration of periodic sync.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
versionId | body | string | No | Required for versioned knowledge bases; use a draft version ID. Scheduled sync is unavailable for versioned data sources. | |
name | body | string | Yes | Data source name. | |
type | body | string | No | Enum: yuque | Data source type; currently only yuque is supported. |
config | body | object | No | Yuque requires a nonempty teamId; repoNamespaces and a syncSchedule cron expression are optional. Versioned data sources cannot set a sync schedule. | |
credentials | body | object | No | Yuque requires a nonempty teamToken; stored credentials are encrypted and ciphertext is not returned. | |
status | body | string | No | Enum: active / disabled | active / disabled; periodic sync is automatically registered when active and config.syncSchedule are configured. |
triggerSync | body | boolean | No | When true (default) and status=active, a full sync is queued immediately after creation. |
Output:
201, returns model Models.KnowledgeBaseDataSource.
| Field | Type | Description |
|---|---|---|
$id* | string | Data source ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Bound knowledge base ID. |
type* | string | Data source type (current enum: yuque). |
name* | string | Data source name. |
config* | object | Non-sensitive configuration (such as repoNamespaces, syncSchedule). |
credentials* | object | Credential metadata; secrets are never echoed back. |
status* | string | Status: active / disabled / error. |
lastSyncAt* | string | Time the most recent sync completed. |
lastSyncStatus* | string | Status of the most recent sync. |
lastCursor* | string | Incremental sync cursor. |
error* | string | Most recent data source error message. |
Call example:
Set APPBASE_API_KEY and YUQUE_TEAM_TOKEN securely in Bash first; this example requires Python 3. Replace the endpoint, project ID, and team details for your environment.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" "${YUQUE_TEAM_TOKEN:?Set YUQUE_TEAM_TOKEN}"
export YUQUE_TEAM_TOKEN
python3 -c "import json, os, sys; json.dump({'name':'team-docs','type':'yuque','config':{'teamId':'acme','repoNamespaces':['acme/manuals'],'syncSchedule':'0 2 * * *'},'credentials':{'teamToken':os.environ['YUQUE_TEAM_TOKEN']},'status':'active','triggerSync':True}, sys.stdout)" |
curl --disable --fail --silent --show-error -i -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @/dev/fd/3 \
-H "Content-Type: application/json" --data-binary @- \
3< <(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY")
)The create response does not wait for sync completion. If sync is triggered, check its record and document ingestion status.
Response example:
{
"$id": "ds_yuque_team",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "team-docs",
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {"teamToken": "********"},
"status": "active",
"lastSyncAt": null,
"lastSyncStatus": null,
"lastCursor": null,
"error": null
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}
SDK:KnowledgeBases.getDataSource · scope:knowledgebases.read
Get a data source by ID (credentials are not echoed back).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; defaults to the current ready version when versioning is enabled. | |
dataSourceId | path | string | Yes | Target data source ID. |
Output:
200, returns model Models.KnowledgeBaseDataSource.
| Field | Type | Description |
|---|---|---|
$id* | string | Data source ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Bound knowledge base ID. |
type* | string | Data source type (current enum: yuque). |
name* | string | Data source name. |
config* | object | Non-sensitive configuration (such as repoNamespaces, syncSchedule). |
credentials* | object | Credential metadata; secrets are never echoed back. |
status* | string | Status: active / disabled / error. |
lastSyncAt* | string | Time the most recent sync completed. |
lastSyncStatus* | string | Status of the most recent sync. |
lastCursor* | string | Incremental sync cursor. |
error* | string | Most recent data source error message. |
Call example:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "ds_yuque_team",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "team-docs",
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {"teamToken": "********"},
"status": "active",
"lastSyncAt": "2026-09-14T02:00:00.000+00:00",
"lastSyncStatus": "ready",
"lastCursor": "yq-2026-09-14T02:00:00Z",
"error": ""
}PATCH /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}
SDK:KnowledgeBases.updateDataSource · scope:knowledgebases.write
Update the data source name, configuration, credentials, or status; credentials are merged key by key rather than replaced wholesale.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
dataSourceId | path | string | Yes | Target data source ID. | |
versionId | body | string | No | Required for versioned knowledge bases; use a draft version ID. Scheduled sync is unavailable for versioned data sources. | |
name | body | string | No | Data source name. | |
config | body | object | No | When provided, validated and replaced as a complete configuration; Yuque requires a nonempty teamId. | |
credentials | body | object | No | When provided, a nonempty teamToken is required; omit the field to keep existing credentials. | |
status | body | string | No | Enum: active / disabled / error / (empty, meaning unrestricted) | active / disabled / error; changing status or config.syncSchedule recalculates the periodic sync schedule. |
Output:
200, returns model Models.KnowledgeBaseDataSource.
| Field | Type | Description |
|---|---|---|
$id* | string | Data source ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Bound knowledge base ID. |
type* | string | Data source type (current enum: yuque). |
name* | string | Data source name. |
config* | object | Non-sensitive configuration (such as repoNamespaces, syncSchedule). |
credentials* | object | Credential metadata; secrets are never echoed back. |
status* | string | Status: active / disabled / error. |
lastSyncAt* | string | Time the most recent sync completed. |
lastSyncStatus* | string | Status of the most recent sync. |
lastCursor* | string | Incremental sync cursor. |
error* | string | Most recent data source error message. |
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals",
"acme/faq"
],
"syncSchedule": "0 */6 * * *"
},
"status": "active"
}'
)Response example:
{
"$id": "ds_yuque_team",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "team-docs",
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals",
"acme/faq"
],
"syncSchedule": "0 */6 * * *"
},
"credentials": {"teamToken": "********"},
"status": "active",
"lastSyncAt": "2026-09-14T02:00:00.000+00:00",
"lastSyncStatus": "ready",
"lastCursor": "yq-2026-09-14T02:00:00Z",
"error": ""
}DELETE /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}
SDK:KnowledgeBases.deleteDataSource · scope:knowledgebases.write
Delete the data source along with its sync history and periodic schedule; knowledge base documents already generated are unaffected.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required when versioning is enabled; use the draft version ID to write. | |
dataSourceId | path | string | Yes | Target data source ID. |
Output:
204, no response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"POST /v1/knowledgebases/{knowledgeBaseId}/datasources/yuque/repos
SDK:KnowledgeBases.listYuqueRepos · scope:knowledgebases.write
Enumerate repositories reachable by the Yuque team using a team token, for choosing repoNamespaces before creating a data source (the token is used once and discarded, never persisted).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
teamId | body | string | Yes | Yuque team ID. | |
teamToken | body | string | Yes | Yuque Open API team token; used only for this query and never stored. |
Output:
200, returns a wide-type JSON object: a list of Yuque team repositories (namespace, name, etc.) for populating the data source config.repoNamespaces.
Call example:
Set APPBASE_API_KEY and YUQUE_TEAM_TOKEN securely in Bash first; this example requires Python 3. Replace the endpoint, project ID, and team details for your environment.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" "${YUQUE_TEAM_TOKEN:?Set YUQUE_TEAM_TOKEN}"
export YUQUE_TEAM_TOKEN
python3 -c "import json, os, sys; json.dump({'teamId':'acme','teamToken':os.environ['YUQUE_TEAM_TOKEN']}, sys.stdout)" |
curl --disable --fail --silent --show-error -i -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/yuque/repos" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @/dev/fd/3 \
-H "Content-Type: application/json" --data-binary @- \
3< <(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY")
)Response example:
{
"repos": [
{
"namespace": "acme/manuals",
"name": "产品手册"
},
{
"namespace": "acme/faq",
"name": "常见问题"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/yuque/docs
SDK:KnowledgeBases.listYuqueDocs · scope:knowledgebases.write
Enumerate importable Yuque documents in selected repositories. The request passes a temporary team token that is not stored.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Target knowledge base ID. | |
teamId | body | string | Yes | Yuque team ID. | |
teamToken | body | string | Yes | Yuque Open API team token (not stored). | |
repoNamespaces | body | string[] | No | Array of repository namespaces; an empty array lists documents across all team repositories. |
Output:
200, returns a wide-type JSON object: a list of importable documents per repository (URL/title, etc.) for batch import selection.
Call example:
Set APPBASE_API_KEY and YUQUE_TEAM_TOKEN securely in Bash first; this example requires Python 3. Replace the endpoint, project ID, and team details for your environment.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" "${YUQUE_TEAM_TOKEN:?Set YUQUE_TEAM_TOKEN}"
export YUQUE_TEAM_TOKEN
python3 -c "import json, os, sys; json.dump({'teamId':'acme','teamToken':os.environ['YUQUE_TEAM_TOKEN'],'repoNamespaces':['acme/manuals']}, sys.stdout)" |
curl --disable --fail --silent --show-error -i -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/yuque/docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @/dev/fd/3 \
-H "Content-Type: application/json" --data-binary @- \
3< <(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY")
)Response example:
{
"docs": [
{
"namespace": "acme/manuals",
"title": "早餐机快速上手",
"url": "<YUQUE_DOCUMENT_URL_1>"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/documents
SDK:KnowledgeBases.createDataSourceDocument · scope:knowledgebases.write
Import a single document from a data source by URL: the URL is only used for locating the document; the server does not fetch the URL directly.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required when versioning is enabled; use the draft version ID to write. | |
dataSourceId | path | string | Yes | Target data source ID. | |
url | body | string | Yes | Yuque document URL; only supported Yuque HTTPS domains and the exact {group}/{book}/{slug} path are accepted. | |
idempotencyKey | body | string | No | Idempotency key. |
Output:
202 newly created or has updates (ingestion enqueued), or 200 content unchanged (document already processing/ready); returns model Models.KnowledgeBaseDocument.409 conflicts with an active ingestion; 503 Yuque is temporarily unavailable.
| Field | Type | Description |
|---|---|---|
$id* | string | Document ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
kbId* | string | Owning knowledge base ID. |
name* | string | Document display name. |
bucketId* | string | Storage bucket ID where the source file resides. |
fileId* | string | Storage file ID of the source file. |
mimeType* | string | MIME type of the source file. |
source* | string | Source: manual manual upload, datasource:{id} data source sync, yuque:personal personal Yuque import. |
externalItemId* | string | External system entry ID; data source sync uses it for deduplication and updates. |
parserId* | string | Document-level chunk strategy override; empty inherits the knowledge base default. |
parserConfig* | object | Document-level parsing/chunk configuration override. |
metadata* | object | Business metadata. |
status* | string | Processing status: uploaded registered / processing processing / ready ready / failed failed. |
enabled* | boolean | Whether it participates in retrieval; when false, chunks are retained but excluded from retrieval results. |
stage* | string | Mirror of the pipeline stage for the current/most recent ingestion. |
activeIngestionId* | string | ID of the current or most recent ingestion task. |
activeGeneration* | string | Retrieval-visible generation; only valid when status=ready. |
processingStartedAt* | string | Time of the most recent processing trigger. |
chunksTotal* | integer | Expected total number of chunks (filled once known). |
chunkCount* | integer | Number of chunks in the active generation. |
error* | string | Most recent processing error message; normally an empty string. |
lastExecutionId* | string | Deprecated legacy Function execution ID. |
Call example:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"url": "<YUQUE_DOCUMENT_URL_1>",
"idempotencyKey": "idem-ds-01"
}'Response example:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "datasource:ds_yuque_team",
"externalItemId": "acme/manuals/breakfast-quickstart",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "processing",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/documents/batch
SDK:KnowledgeBases.createDataSourceDocumentsBatch · scope:knowledgebases.write
Batch import documents from a data source by URL (up to 20 items, with per-item results returned).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | body | string | No | Required when versioning is enabled; use the draft version ID to write. | |
dataSourceId | path | string | Yes | Target data source ID. | |
urls | body | string[] | Yes | Array of Yuque document URLs, up to 20 items, no duplicates. | |
idempotencyKey | body | string | No | Batch idempotency key prefix. |
Output:
200 all accepted/unchanged, 207 when any failed exists; returns model Models.KnowledgeBaseDataSourceDocumentImportBatch (results[] matches the request order and must be checked item by item). Empty list / more than 20 items / duplicate URLs / data source not active return 400.
| Field | Type | Description |
|---|---|---|
total* | integer | Number of URLs processed this time. |
accepted* | integer | Number of URLs whose documents were created/updated and ingestion enqueued. |
unchanged* | integer | Number of URLs left untouched because remote content was already processing/ready. |
failed* | integer | Number of URLs that failed validation or import. |
results* | object[] | Per-URL results arranged in request order. |
url* | string | Requested Yuque document URL. |
status* | string | Per-URL import outcome: accepted, unchanged, or failed. |
document | object | Imported knowledge base document when status is accepted or unchanged. |
error | string | Human-readable failure detail when status is failed. |
errorType | string | Machine-readable AppBase exception type when status is failed. |
Call example:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/documents/batch" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"<YUQUE_DOCUMENT_URL_1>",
"<YUQUE_DOCUMENT_URL_2>"
],
"idempotencyKey": "idem-ds-batch-01"
}'Response example:
{
"total": 2,
"accepted": 0,
"unchanged": 0,
"failed": 0,
"results": [
{
"url": "",
"status": "available",
"document": {},
"error": "",
"errorType": ""
},
{
"url": "",
"status": "available",
"document": {},
"error": "",
"errorType": ""
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs
SDK:KnowledgeBases.listDataSourceSyncs · scope:knowledgebases.read
List data source sync records (in reverse order of creation time), filterable by status.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; defaults to the current ready version when versioning is enabled. | |
dataSourceId | path | string | Yes | Target data source ID. | |
status | query | string | No | Default "" | Filter by sync status: queued / running / ready / failed. |
Output:
200, returns model Models.KnowledgeBaseDataSourceSyncList.
| Field | Type | Description |
|---|---|---|
total* | integer | Total number of sync records matching the query. |
syncs* | object[] | List of sync records (in reverse order of creation time). |
$id* | string | Sync record ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
datasourceId* | string | Data source ID. |
kbId* | string | Knowledge base ID. |
status* | string | Sync status: queued / running / ready / failed. |
cursorStart* | string | Cursor at the start of the sync. |
cursorEnd* | string | New cursor produced by the sync. |
stats* | object | Sync counts: created, updated, skipped, disabled, and failed. |
error* | string | Error message when failed. |
startedAt* | string | Time the worker started processing. |
finishedAt* | string | Sync end time. |
Call example:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs?status=ready" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 1,
"syncs": [
{
"$id": "sync_771f",
"$createdAt": "2026-09-14T02:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:01:12.000+00:00",
"datasourceId": "ds_yuque_team",
"kbId": "kb_product_docs",
"status": "ready",
"cursorStart": "yq-2026-09-13T02:00:00Z",
"cursorEnd": "yq-2026-09-14T02:00:00Z",
"stats": {
"created": 1,
"updated": 2,
"skipped": 36,
"disabled": 0,
"failed": 0
},
"error": "",
"startedAt": "2026-09-14T02:00:01.000+00:00",
"finishedAt": "2026-09-14T02:01:12.000+00:00"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs
SDK:KnowledgeBases.createDataSourceSync · scope:knowledgebases.write
Trigger a data source sync; if a queued/running sync already exists, the existing record is returned without enqueueing again.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
dataSourceId | path | string | Yes | Target data source ID. | |
versionId | body | string | No | Required when versioning is enabled; use the target draft version ID. |
Output:
202, returns model Models.KnowledgeBaseDataSourceSync.Asynchronous task: poll GET .../syncs/{syncId} until ready/failed.
| Field | Type | Description |
|---|---|---|
$id* | string | Sync record ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
datasourceId* | string | Data source ID. |
kbId* | string | Knowledge base ID. |
status* | string | Sync status: queued / running / ready / failed. |
cursorStart* | string | Cursor at the start of the sync. |
cursorEnd* | string | New cursor produced by the sync. |
stats* | object | Sync counts: created, updated, skipped, disabled, and failed. |
error* | string | Error message when failed. |
startedAt* | string | Time the worker started processing. |
finishedAt* | string | Sync end time. |
Call example:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"When versioning is enabled, send the actual draft ID in the request body:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" -d '{"versionId":"<DRAFT_VERSION_ID>"}'Response example:
{
"$id": "sync_771f",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"datasourceId": "ds_yuque_team",
"kbId": "kb_product_docs",
"status": "queued",
"cursorStart": "yq-2026-09-13T02:00:00Z",
"cursorEnd": null,
"stats": {
"created": 0,
"updated": 0,
"skipped": 0,
"disabled": 0,
"failed": 0
},
"error": null,
"startedAt": null,
"finishedAt": null
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs/{syncId}
SDK:KnowledgeBases.getDataSourceSync · scope:knowledgebases.read
Query the status, cursor advancement, and statistics of a single sync.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | Yes | Owning knowledge base ID. | |
versionId | query | string | No | Optional; defaults to the current ready version when versioning is enabled. | |
dataSourceId | path | string | Yes | Target data source ID. | |
syncId | path | string | Yes | Target sync record ID. |
Output:
200, returns model Models.KnowledgeBaseDataSourceSync.
| Field | Type | Description |
|---|---|---|
$id* | string | Sync record ID. |
$createdAt* | string | Creation time (ISO 8601). |
$updatedAt* | string | Last update time (ISO 8601). |
datasourceId* | string | Data source ID. |
kbId* | string | Knowledge base ID. |
status* | string | Sync status: queued / running / ready / failed. |
cursorStart* | string | Cursor at the start of the sync. |
cursorEnd* | string | New cursor produced by the sync. |
stats* | object | Sync counts: created, updated, skipped, disabled, and failed. |
error* | string | Error message when failed. |
startedAt* | string | Time the worker started processing. |
finishedAt* | string | Sync end time. |
Call example:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs/sync_771f" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "sync_771f",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"datasourceId": "ds_yuque_team",
"kbId": "kb_product_docs",
"status": "ready",
"cursorStart": "yq-2026-09-13T02:00:00Z",
"cursorEnd": "yq-2026-09-14T02:00:00Z",
"stats": {
"created": 1,
"updated": 2,
"skipped": 36,
"disabled": 0,
"failed": 0
},
"error": "",
"startedAt": "2026-09-14T02:00:01.000+00:00",
"finishedAt": "2026-09-14T02:01:12.000+00:00"
}Lexicons and binding management
GET /v1/lexicons
SDK:Lexicons.list · scope:lexicons.read
List in pages all lexicons visible in the current project.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
limit | query | integer | No | Default 25 | Number of items returned per page, range 1–100. |
offset | query | integer | No | Default 0 | Pagination offset, range 0–1000000. |
output: 200 OK, returns lexiconList models (total + lexicons[]).
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "<APPBASE_ENDPOINT_WITH_V1>/lexicons?limit=25&offset=0" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)Response example:
{
"total": 2,
"lexicons": [
{
"$id": "lex_enterprise_synonyms",
"$createdAt": "2026-10-21T08:00:00.000+00:00",
"$updatedAt": "2026-10-22T03:15:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "企业智能客服同义词与扩展词典",
"description": "统一 OceanBase、AI 网关与智能客服业务术语标准表达",
"tokenizerProfile": "unicode-v1",
"revision": 4
},
{
"$id": "lex_support_stopwords",
"$createdAt": "2026-10-21T08:10:00.000+00:00",
"$updatedAt": "2026-10-21T09:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "客服检索与对话停用词词典",
"description": "过滤口语冗余词与违规阻断词",
"tokenizerProfile": "unicode-v1",
"revision": 2
}
]
}POST /v1/lexicons
SDK:Lexicons.create · scope:lexicons.write
Create a new lexicon in the project.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
lexiconId | body | string | No | Default "unique()" | Custom lexicon ID (e.g. lex_enterprise_synonyms), or pass "unique()". |
name | body | string | Yes | — | Lexicon name, 1–128 characters long. |
description | body | string | No | Default "" | Lexicon purpose description, up to 4096 characters. |
permissions | body | string[] | No | Default null | Array of resource-level permissions (only read, update, delete actions allowed). |
Output : 201 Created, returns a lexicon model.
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/lexicons" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"lexiconId": "lex_enterprise_synonyms",
"name": "企业智能客服同义词与扩展词典",
"description": "统一 OceanBase、AI 网关与智能客服业务术语标准表达"
}'
)GET /v1/lexicons/{lexiconId}、PATCH /v1/lexicons/{lexiconId}、DELETE /v1/lexicons/{lexiconId}
SDK:Lexicons.get / Lexicons.update / Lexicons.delete · scope:lexicons.read / lexicons.write
| Method + path | Parameter | Location | Type | Required | Description |
|---|---|---|---|---|---|
GET /v1/lexicons/{lexiconId} | lexiconId | path | string | Yes | Get lexicon details by ID (including the current revision and tokenizerProfile). |
PATCH /v1/lexicons/{lexiconId} | lexiconId | path | string | Yes | Target lexicon ID. |
PATCH /v1/lexicons/{lexiconId} | name | body | string | No | Updated lexicon name (1–128 characters). |
PATCH /v1/lexicons/{lexiconId} | description | body | string | No | Updated lexicon description (up to 4096 characters). |
PATCH /v1/lexicons/{lexiconId} | permissions | body | string[] | No | Array of resource-level permissions (revision is atomically incremented after the update). |
DELETE /v1/lexicons/{lexiconId} | lexiconId | path | string | Yes | Delete the lexicon and all of its entries (returns 204); if it is still bound to any knowledge base or agent, returns 409 general_conflict. |
Call example:
Set APPBASE_ENDPOINT to the target environment API endpoint (including /v1), and confirm the project and credentials belong to that environment.
Get lexicon details
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "${APPBASE_ENDPOINT}/lexicons/lex_enterprise_synonyms" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @-
)Update the lexicon name and description
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PATCH "${APPBASE_ENDPOINT}/lexicons/lex_enterprise_synonyms" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"name": "企业智能客服同义词与扩展词典(v2)",
"description": "覆盖 OceanBase V4.3、LLM Gateway 与智能体专有术语"
}'
)Delete an unbound lexicon. Run separately only after confirming the target and consequences.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X DELETE "${APPBASE_ENDPOINT}/lexicons/lex_temp_test" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @-
)GET /v1/lexicons/{lexiconId}/entries and POST /v1/lexicons/{lexiconId}/entries
SDK:Lexicons.listEntries / Lexicons.createEntry · scope:lexicons.read / lexicons.write
Manage structured lexicon entry rules within a lexicon.
Create lexicon entry (POST /v1/lexicons/{lexiconId}/entries) input parameters:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
lexiconId | path | string | Yes | — | Target lexicon ID. |
entryId | body | string | No | Default "unique()" | Lexicon entry ID. |
entryType | body | string | Yes | Enum synonym, expansion, stop | Rule type: synonym (bidirectional equivalent synonym), expansion (one-way hyponym expansion term), stop (stopword/blocklist word). |
terms | body | string[] | yes | — | Trigger term array (1–100 items, each 1–256 characters); when synonym, the first item is the Canonical Term. |
expansions | body | string[] | no | default [] | Required only when entryType="expansion"; fill in the array of expanded target terms. |
position | body | integer | no | default 0 | Rule matching sort priority (0–2147483647, lower takes precedence). |
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/lexicons/lex_enterprise_synonyms/entries" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"entryId": "unique()",
"entryType": "synonym",
"terms": ["OceanBase", "OB数据库", "蚂蚁分布式数据库"],
"expansions": [],
"position": 10
}'
)Response example (201 Created):
{
"$id": "ent_ob_syn_01",
"$createdAt": "2026-10-22T03:15:00.000+00:00",
"$updatedAt": "2026-10-22T03:15:00.000+00:00",
"lexiconId": "lex_enterprise_synonyms",
"entryType": "synonym",
"terms": ["OceanBase", "OB数据库", "蚂蚁分布式数据库"],
"expansions": [],
"position": 10
}POST /v1/lexicons/{lexiconId}/preview、POST /v1/lexicons/{lexiconId}/import、GET /v1/lexicons/{lexiconId}/export、GET /v1/lexicons/{lexiconId}/references
SDK:Lexicons.preview / Lexicons.import / Lexicons.export / Lexicons.listReferences · scope:lexicons.read / lexicons.write
| endpoint | core parameters | return model / format | description |
|---|---|---|---|
POST /v1/lexicons/{lexiconId}/preview | query (body, string, required) | Models.LexiconRewrite | Preview the normalized text after lexicon rewriting for a single query sentence, including synonym replacement, expansion term expansion, and stopword hit details. |
POST /v1/lexicons/{lexiconId}/import | format (json/csv/xlsx), mode (merge/overwrite), dryRun (boolean, default true), content / entries | Models.LexiconImportResult | Batch import lexicon entries (first use dryRun: true to validate deduplication and the 1,000 entry quota, then call dryRun: false to persist officially and increment revision). |
GET /v1/lexicons/{lexiconId}/export | format (query: json/csv/xlsx) | file stream / JSON | Export all lexicon entry rules of the specified lexicon. |
GET /v1/lexicons/{lexiconId}/references | lexiconId (path, string, required) | Models.LexiconReferenceList | Query the list of knowledgebases and agents resource references currently bound to this lexicon. |
call example (rewrite preview POST /v1/lexicons/{lexiconId}/preview):
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/lexicons/lex_enterprise_synonyms/preview" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"query": "请问OB数据库向量索引报错怎么排查"
}'
)Response example (200 OK):
{
"originalQuery": "请问OB数据库向量索引报错怎么排查",
"rewrittenQuery": "OceanBase 向量索引报错怎么排查",
"expandedTerms": [
"OceanBase",
"OB数据库",
"HNSW索引",
"IVF索引"
],
"removedStopwords": [
"请问"
],
"matchedEntries": [
{
"entryId": "ent_ob_syn_01",
"entryType": "synonym",
"matchedTerm": "OB数据库",
"canonicalTerm": "OceanBase"
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/lexicons and PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons
SDK:Lexicons.getKnowledgeBaseBindings / Lexicons.updateKnowledgeBaseBindings · scope:lexicons.read / lexicons.write
Query or wholesale replace the lexicon list and enablement status bound to the specified knowledge base (e.g., kb_enterprise_support).
PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons input parameters:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | yes | — | Target knowledge base ID. |
enabled | body | boolean | no | default false | Whether to enable lexicon rewriting for retrieval and preprocessing of this knowledge base. |
bindings | body | object[] | yes | — | Ordered binding array (up to 100 items), each in the format {"lexiconId": "<id>", "priority": <int>}. |
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PUT "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/lexicons" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"bindings": [
{"lexiconId": "lex_enterprise_synonyms", "priority": 1},
{"lexiconId": "lex_support_stopwords", "priority": 2}
]
}'
)(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# Query the list of lexicons currently bound to the knowledge base (GET /v1/knowledgebases/{kbId}/lexicons)
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "<APPBASE_ENDPOINT_WITH_V1>/knowledgebases/kb_enterprise_support/lexicons" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)Response example (200 OK):
{
"enabled": true,
"stopIntercept": false,
"stopReply": "",
"bindings": [
{
"lexiconId": "lex_enterprise_synonyms",
"priority": 1
},
{
"lexiconId": "lex_support_stopwords",
"priority": 2
}
]
}Note: The current project agent workbench (Agent Runtime Workbench) supports binding the same project lexicon via the isomorphic endpoints
GET /v1/agent-runtime/project/lexiconsandPUT /v1/agent-runtime/project/lexicons(additionally supportingstopIntercept: trueandstopReplyblocked-phrase configuration); see Agent Runtime API.
Errors and boundaries
Knowledge base/document/chunk/data source/sync/ingestion does not exist:
404+knowledge_base_not_foundand other corresponding types; duplicate ID:409.embeddingModelis fixed when the knowledge base is created: modification requires rebuilding the knowledge base and re-ingesting; document-levelparserIdoverrides can further be applied at ingestion time viaoverrides.Embedding/reranking depends on LLM Gateway: when the provider is unavailable or quota is exhausted, ingestion/retrieval returns a dependency failure error — check the provider health status of llm-gateway.
Batch import limits: 50 files / 20 URLs; check each item in a
207multi-status response; do not assume any item succeeded.Documents of
enabled=falseare excluded from retrieval results but chunks are retained; deleting a document cascades to delete chunks and vectors.Yuque team tokens and OAuth credentials are sensitive credentials: after
credentialswrite, they are not echoed back; after an OAuth session expires, it must be recreated.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
KnowledgeBases.list / create / get / update / delete | /knowledgebases CRUD |
KnowledgeBases.createSearch / createMultiSearch | POST .../{id}/search、POST /knowledgebases/search |
KnowledgeBases.getManagement / createReindex | GET .../management、POST .../reindex |
KnowledgeBases.listDocuments / createDocument / createDocumentsBatch / getDocument / updateDocument / deleteDocument | /knowledgebases/{id}/documents* |
KnowledgeBases.createDocumentProcess / getDocumentSource | POST .../process、GET .../source |
KnowledgeBases.listChunks / createChunk / getChunk / updateChunk / deleteChunk | .../chunks* |
KnowledgeBases.listIngestions / createIngestion / getIngestion / deleteIngestion | .../ingestions* |
KnowledgeBases.listDataSources / createDataSource / getDataSource / updateDataSource / deleteDataSource | .../datasources* |
KnowledgeBases.listYuqueRepos / listYuqueDocs | POST .../datasources/yuque/repos|docs |
KnowledgeBases.createDataSourceDocument / createDataSourceDocumentsBatch / listDataSourceSyncs / createDataSourceSync / getDataSourceSync | .../datasources/{dataSourceId}/documents*、syncs* |
Lexicons.list / create / get / update / delete | /v1/lexicons CRUD |
Lexicons.listEntries / createEntry / getEntry / updateEntry / deleteEntry | /v1/lexicons/{lexiconId}/entries* |
Lexicons.preview / import / export / listReferences | /v1/lexicons/{lexiconId}/preview|import|export|references |
Lexicons.getKnowledgeBaseBindings / updateKnowledgeBaseBindings | GET|PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons |
2.12.0 endpoints and compatibility
Paths below are relative to /v1. Server requests carry X-Appwrite-Project and X-Appwrite-Key; keep the key on the server. Scopes below are necessary; dataset access, ownership and resource state may add checks. HTTP 202 means accepted; use the returned operation identifier to read its terminal result.
| HTTP | Scope | SDK |
|---|---|---|
POST /knowledgebases/project-scopes | knowledgebases.write | knowledgeBases.createProjectScope |
GET /knowledgebases/project-scopes/{projectId} | knowledgebases.read | knowledgeBases.getProjectScope |
PATCH /knowledgebases/project-scopes/{projectId} | knowledgebases.write | knowledgeBases.updateProjectScope |
POST /knowledgebases/search | knowledgebases.read | knowledgeBases.createMultiSearch |
GET /knowledgebases/{knowledgeBaseId}/document-directories | knowledgebases.read | knowledgeBases.listDocumentDirectories |
POST /knowledgebases/{knowledgeBaseId}/document-directories/count | knowledgebases.read | knowledgeBases.countDocumentDirectories |
GET /knowledgebases/{knowledgeBaseId}/documents | knowledgebases.read | knowledgeBases.listDocuments |
POST /knowledgebases/{knowledgeBaseId}/documents | knowledgebases.write | knowledgeBases.createDocument |
POST /knowledgebases/{knowledgeBaseId}/documents/batch | knowledgebases.write | knowledgeBases.createDocumentsBatch |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId} | knowledgebases.write | knowledgeBases.updateDocument |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId} | knowledgebases.write | knowledgeBases.updateChunk |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/content | knowledgebases.read | knowledgeBases.getDocumentContent |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact | knowledgebases.read | knowledgeBases.getDocumentParseArtifact |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content | knowledgebases.read | knowledgeBases.getDocumentParseArtifactContent |
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations | knowledgebases.read | knowledgeBases.listEnhancementOperations |
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations | knowledgebases.write | knowledgeBases.createEnhancementOperation |
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId} | knowledgebases.read | knowledgeBases.getEnhancementOperation |
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId}/cancel | knowledgebases.write | knowledgeBases.cancelEnhancementOperation |
GET /knowledgebases/{knowledgeBaseId}/graph | knowledgebases.read | knowledgeBases.getGraph |
POST /knowledgebases/{knowledgeBaseId}/graph/search | knowledgebases.read | knowledgeBases.createGraphSearch |
GET /knowledgebases/{knowledgeBaseId}/lexicons | lexicons.read | lexicons.getKnowledgeBaseBindings |
PUT /knowledgebases/{knowledgeBaseId}/lexicons | lexicons.write | lexicons.updateKnowledgeBaseBindings |
POST /knowledgebases/{knowledgeBaseId}/search | knowledgebases.read | knowledgeBases.createSearch |
GET /knowledgebases/{knowledgeBaseId}/wiki/graph | knowledgebases.read | knowledgeBases.getWikiGraph |
GET /knowledgebases/{knowledgeBaseId}/wiki/pages | knowledgebases.read | knowledgeBases.listWikiPages |
POST /knowledgebases/{knowledgeBaseId}/wiki/search | knowledgebases.read | knowledgeBases.createWikiSearch |
GET /lexicons | lexicons.read | lexicons.list |
POST /lexicons | lexicons.write | lexicons.create |
GET /lexicons/{lexiconId} | lexicons.read | lexicons.get |
PATCH /lexicons/{lexiconId} | lexicons.write | lexicons.update |
DELETE /lexicons/{lexiconId} | lexicons.write | lexicons.delete |
GET /lexicons/{lexiconId}/entries | lexicons.read | lexicons.listEntries |
POST /lexicons/{lexiconId}/entries | lexicons.write | lexicons.createEntry |
GET /lexicons/{lexiconId}/entries/{entryId} | lexicons.read | lexicons.getEntry |
PATCH /lexicons/{lexiconId}/entries/{entryId} | lexicons.write | lexicons.updateEntry |
DELETE /lexicons/{lexiconId}/entries/{entryId} | lexicons.write | lexicons.deleteEntry |
GET /lexicons/{lexiconId}/export | lexicons.read | lexicons.export |
POST /lexicons/{lexiconId}/import | lexicons.write | lexicons.import |
POST /lexicons/{lexiconId}/preview | lexicons.read | lexicons.preview |
GET /lexicons/{lexiconId}/references | lexicons.read | lexicons.listReferences |
POST /knowledgebases/project-scopes
Register a project scope
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
projectId | body | yes | string | — | Customer-facing project identifier. 1-64 letters/digits. |
name | body | no | string | default="" | Optional display name used for team naming. |
subProductId | body | no | string | default="" | Bound sub-product code. Optional, can be bound later. |
knowledgeBaseId | body | no | string | default="" | Existing knowledge base to bind as the project asset store. Optional; bind later via update. |
Success response: HTTP 201 — knowledgeBaseProjectScope.
Response fields: $id (string), $createdAt (string), $updatedAt (string), projectId (string), name (string), knowledgeBaseId (string), teamId (string), subProductId (string).
GET /knowledgebases/project-scopes/{projectId}
Get a project scope
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
projectId | path | yes | string | — | Customer-facing project identifier. |
Success response: HTTP 200 — knowledgeBaseProjectScope.
Response fields: $id (string), $createdAt (string), $updatedAt (string), projectId (string), name (string), knowledgeBaseId (string), teamId (string), subProductId (string).
PATCH /knowledgebases/project-scopes/{projectId}
Update a project scope
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
projectId | path | yes | string | — | Customer-facing project identifier. |
name | body | no | string | default="" | Display name. Empty keeps the current value. |
subProductId | body | no | string | default="" | Bound sub-product code. Empty keeps the current binding; pass a new code to rebind. There is no clear sentinel — clearing requires rebinding or platform assistance. |
knowledgeBaseId | body | no | string | default="" | Knowledge base to bind as the project asset store. Empty keeps the current binding; "none" clears it. |
Success response: HTTP 200 — knowledgeBaseProjectScope.
Response fields: $id (string), $createdAt (string), $updatedAt (string), projectId (string), name (string), knowledgeBaseId (string), teamId (string), subProductId (string).
POST /knowledgebases/search
Search multiple knowledge bases
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseIds | body | no | array[string] | default=[] | Knowledge base IDs. Between 1 and 10 unique IDs are required when projectId is omitted. Omit when projectId is set so the server expands the three-layer search range. |
query | body | yes | string | — | Search query text. |
limit | body | no | integer | format=int32; default=10 | Final number of results to return across all knowledge bases. |
searchMode | body | no | string | enum=vector, fulltext, hybrid; default="hybrid" | Search mode: vector, fulltext, or hybrid. |
rerank | body | no | boolean | default=false | Whether to rerank the merged recall results once via LLM Gateway. |
recallLimit | body | no | integer | format=int32 | Global recall width when rerank is enabled. Defaults to max(limit×4, 20). |
rerankModel | body | no | string | default="" | Optional explicit rerank model ID. Overrides automatic provider selection when rerank is enabled. |
rerankProviderRef | body | no | string | — | Pinned rerank provider source as project:<providerId> or trial:<bindingId>. Omit to use automatic routing. Do not use providerType:providerId. |
similarityThreshold | body | no | number | format=float | Minimum vector similarity applied to every knowledge base. Each knowledge base default is used when omitted. |
vectorWeight | body | no | number | format=float | Hybrid vector branch weight applied to every knowledge base. Each knowledge base default is used when omitted. |
projectId | body | no | string | — | Optional customer project identifier. When set, knowledgeBaseIds must be omitted: the server expands the project layer (whole project knowledge base), the bound sub-product layer (narrowed by the bound subProductId) and the common layer, after a fail-closed project membership check. |
documentTag | body | no | string | — | Optional tag {subProductId}_{sectionCode}_{fileKey} or multiple comma-separated tags (any-match); free-form values are also accepted., applied per knowledge base chunk recall. |
subProductId | body | no | string | — | Optional sub-product code applied per knowledge base. Restricts chunk recall to documents of this sub-product. |
offset | body | no | integer | format=int32; default=0 | Number of ranked results to skip across the fused ranking. Combine with limit for pagination. |
metadataFilter | body | no | object | default={} | Optional document metadata filter keyed by knowledge base ID, with an optional "*" entry applied to every knowledge base without its own key. Matching documents are selected before that knowledge base's chunk recall. |
Success response: HTTP 200 — knowledgeBaseMultiSearchResultList.
Response fields: stopped (boolean), effectiveQuery (string), stopReply (string), total (integer), results (array), reranked (boolean).
GET /knowledgebases/{knowledgeBaseId}/document-directories
List document directories
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
parentPath | query | no | string | default="" | Parent directory path; empty means root. |
limit | query | no | integer | format=int32; default=100 | Maximum number of directories. |
offset | query | no | integer | format=int32; default=0 | Directory page offset. |
versionId | query | no | string | — | Optional Knowledge Base Version ID. |
Success response: HTTP 200 — any.
POST /knowledgebases/{knowledgeBaseId}/document-directories/count
Count documents in directory union
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
paths | body | no | array[string] | default=[] | Directory paths; counts the document union. |
versionId | body | no | string | — | Optional Knowledge Base Version ID. |
groups | body | no | array[string] | — | Optional batch of directory unions, at most 100 groups per request. Mutually exclusive with nonempty paths. |
Success response: HTTP 200 — any.
GET /knowledgebases/{knowledgeBaseId}/documents
List knowledge base documents
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
status | query | no | string | default="" | Filter documents by status. |
stage | query | no | string | default="" | Filter documents by stage. |
enabled | query | no | boolean | — | Filter documents by enabled status. |
documentTag | query | no | string | — | Optional tag {subProductId}_{sectionCode}_{fileKey} exact match on metadata.documentTag; free-form values are also accepted. |
subProductId | query | no | string | — | Optional sub-product code. Returns only documents whose metadata.subProductId (or documentTag subProductId segment) equals this value. Combine with documentTag to require both. |
queries | query | no | array[string] | default=[] | Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. Ignored when documentTag or subProductId is set. |
versionId | query | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version for ACTIVE Knowledge Bases. |
directoryPath | query | no | string | — | Normalized directory path, including descendants. |
directoryUnclassified | query | no | boolean | default=false | Only documents without a directory. |
Success response: HTTP 200 — knowledgeBaseDocumentList.
Response fields: total (integer), documents (array).
POST /knowledgebases/{knowledgeBaseId}/documents
Create knowledge base document
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
bucketId | body | no | string | default="" | Optional Storage bucket ID of the already-uploaded source file. Defaults to the knowledge base bucket. |
fileId | body | yes | string | — | Storage file ID of the already-uploaded source file. |
name | body | no | string | default="" | Optional document display name. Defaults to the storage file name. |
documentTag | body | no | string | default="" | Optional tag {subProductId}_{sectionCode}_{fileKey}; fileKey may be omitted ({subProductId}_{sectionCode}) and is generated server-side. Multiple tags comma-separated in one value (tag1,tag2); free-form values are also accepted. Stored as a list in metadata.documentTag. |
subProductId | body | no | string | default="" | Optional sub-product code (1–64 letters or digits), saved in the independent metadata.subProductId field. When a nonempty documentTag is submitted and this field is omitted or cleared, derivation occurs only if the first tag is a valid structured identifier with a nonempty sub-product segment. |
projectId | body | no | string | default="" | Optional customer project identifier (1-64 letters/digits) stored in metadata.projectId. Marks this document as project-owned; the shared-library layout (6.2 option B) filters recall by it. |
sectionCode | body | no | string | default="" | Optional section code (1-64 digits) embedded as the sectionCode segment of the auto-generated documentTag when documentTag is omitted. |
source | body | no | string | default="manual" | Document source. Default: manual. |
externalItemId | body | no | string | default="" | External item ID when the document originates from an external data source. |
parserId | body | no | string | enum=general, title, smart, regex, faq, sheet | Optional document-level chunking strategy override. An omitted value inherits the Knowledge Base default and is checked against the concrete file. Excel .xls/.xlsx documents directly support faq or sheet; smart automatically resolves to sheet. Sheet is unavailable for other formats. |
parserConfig | body | no | object | — | Optional document-level parser configuration override. |
metadata | body | no | object | default=[] | Optional business metadata. |
versionId | body | no | string | — | Optional DRAFT knowledge-base version ID. Required for writes when Versioning is ACTIVE. |
Success response: HTTP 201 — knowledgeBaseDocument.
Response fields: $id (string), $createdAt (string), $updatedAt (string), kbId (string), versionId (string), name (string), bucketId (string), fileId (string), mimeType (string), source (string), externalItemId (string), parserId (string), parserConfig (object), metadata (object), status (string), enabled (boolean), stage (string), activeIngestionId (string), activeGeneration (string), processingStartedAt (string), chunksTotal (integer), chunkCount (integer), error (string), lastExecutionId (string).
POST /knowledgebases/{knowledgeBaseId}/documents/batch
Create knowledge base documents in a batch
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
fileIds | body | yes | array[string] | — | Storage file IDs to register as documents. Maximum 50 files. |
bucketId | body | no | string | default="" | Optional Storage bucket ID. Defaults to the knowledge base bucket. |
source | body | no | string | default="manual" | Document source. Default: manual. |
parserId | body | no | string | enum=general, title, smart, regex, faq, sheet | Optional document-level chunking strategy override. An omitted value inherits the Knowledge Base default and is checked against every concrete file. Excel .xls/.xlsx documents directly support faq or sheet; smart automatically resolves to sheet. Sheet is unavailable for other formats. |
parserConfig | body | no | object | — | Optional document-level parser configuration override. |
metadata | body | no | object | default=[] | Optional business metadata shared by all documents. |
documentTag | body | no | string | default="" | Optional tag {subProductId}_{sectionCode}_{fileKey}; fileKey may be omitted ({subProductId}_{sectionCode}) and is generated server-side per document. Multiple tags comma-separated in one value (tag1,tag2); free-form values are also accepted. Applied to every document in the batch. Stored as a list in metadata.documentTag. |
subProductId | body | no | string | default="" | Optional sub-product code (1–64 letters or digits) applied to every document and saved in the independent metadata.subProductId field. When a nonempty documentTag is submitted and this field is omitted or cleared, derivation occurs only if the first tag is a valid structured identifier with a nonempty sub-product segment. |
projectId | body | no | string | default="" | Optional customer project identifier (1-64 letters/digits) stored in every document metadata.projectId. Marks documents as project-owned; the shared-library layout (6.2 option B) filters recall by it. |
sectionCode | body | no | string | default="" | Optional section code (1-64 digits) embedded as the sectionCode segment of each auto-generated documentTag when documentTag is omitted. |
versionId | body | no | string | — | Optional DRAFT knowledge-base version ID. Required for writes when Versioning is ACTIVE. |
Success response: HTTP 201 — knowledgeBaseDocumentList.
Response fields: total (integer), documents (array).
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId}
Update knowledge base document
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
documentId | path | yes | string | — | Knowledge base document ID. |
name | body | no | string | — | Document display name. |
documentTag | body | no | string | — | Optional tag {subProductId}_{sectionCode}_{fileKey}; fileKey may be omitted ({subProductId}_{sectionCode}) and is generated server-side, or multiple tags comma-separated in one value (tag1,tag2). Free-form values are also accepted. Pass an empty string to clear metadata.documentTag. |
subProductId | body | no | string | — | Optional sub-product code saved in the independent metadata.subProductId field. Clearing this field alone can leave the effective filter falling back to an existing structured tag; clear documentTag as well to remove both associations. When a nonempty documentTag is submitted and this field is omitted or cleared, derivation occurs only if the first tag is a valid structured identifier with a nonempty sub-product segment. |
projectId | body | no | string | — | Optional customer project identifier stored in metadata.projectId. Pass an empty string to clear. Marks the document as project-owned for shared-library recall filtering. |
parserId | body | no | string | enum=general, title, smart, regex, faq, sheet | Document-level chunking strategy override. Excel .xls/.xlsx documents directly support faq or sheet; smart automatically resolves to sheet. Sheet is unavailable for other formats. Pass an empty string to clear the override and validate the inherited Knowledge Base default against the concrete file. |
parserConfig | body | no | object | — | Document-level parser configuration override. |
metadata | body | no | object | default={} | Optional business metadata. Replaces existing business metadata while preserving metadata.documentTag unless documentTag is explicitly provided. |
enabled | body | no | boolean | — | Whether the document is enabled and eligible for search retrieval. Disabled documents are excluded from knowledge base search results. |
status | body | no | string | — | Processing status (API key only, legacy). |
stage | body | no | string | — | Processing stage (API key only, legacy). |
chunksTotal | body | no | integer | format=int32 | Total chunks (API key only, legacy). |
chunkCount | body | no | integer | format=int32 | Chunk count (API key only, legacy). |
error | body | no | string | — | Error message (API key only, legacy). |
versionId | body | no | string | — | Optional DRAFT knowledge-base version ID. Required for writes when Versioning is ACTIVE. |
Success response: HTTP 200 — knowledgeBaseDocument.
Response fields: $id (string), $createdAt (string), $updatedAt (string), kbId (string), versionId (string), name (string), bucketId (string), fileId (string), mimeType (string), source (string), externalItemId (string), parserId (string), parserConfig (object), metadata (object), status (string), enabled (boolean), stage (string), activeIngestionId (string), activeGeneration (string), processingStartedAt (string), chunksTotal (integer), chunkCount (integer), error (string), lastExecutionId (string).
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
Update knowledge base document chunk
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
documentId | path | yes | string | — | Knowledge base document ID. |
chunkId | path | yes | string | — | Chunk ID. |
content | body | no | string | — | Chunk text content. Recomputes the embedding vector together with persisted image descriptions. |
metadata | body | no | object | default={} | Optional arbitrary chunk metadata. Recomputes the embedding vector when image descriptions change. |
enabled | body | no | boolean | — | Whether the chunk is enabled for retrieval. Disabled chunks are excluded from knowledge base search results and stay disabled across document publish cycles. |
versionId | body | no | string | — | Optional DRAFT knowledge-base version ID. Required for writes when Versioning is ACTIVE. |
Success response: HTTP 200 — knowledgeBaseChunk.
Response fields: $id (string), $createdAt (string), $updatedAt (string), documentId (string), versionId (string), content (string), ingestVersion (string), enabled (boolean), source (object), locator (object), metadata (object).
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/content
Get knowledge base document content
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
documentId | path | yes | string | — | Knowledge base document ID. |
versionId | query | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version for ACTIVE Knowledge Bases. |
Success response: HTTP 200 — knowledgeBaseDocumentContent.
Response fields: knowledgeBaseId (string), documentId (string), name (string), mimeType (string), status (string), generation (string), chunksTotal (integer), truncated (boolean), content (string).
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact
Get knowledge base document parse artifact status
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
documentId | path | yes | string | — | Knowledge base document ID. |
versionId | query | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version for ACTIVE Knowledge Bases. |
Success response: HTTP 200 — knowledgeBaseDocumentParseArtifact.
Response fields: knowledgeBaseId (string), documentId (string), status (string), supported (boolean), generation (string), byteSize (integer), sha256 (string).
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content
Get knowledge base document parse artifact content
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
documentId | path | yes | string | — | Knowledge base document ID. |
versionId | query | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version for ACTIVE Knowledge Bases. |
Success response: HTTP 200 — File.
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations
List Knowledge Base content enhancement operations
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
kind | query | no | string | enum=enhance, clear; default="" | Optional operation kind filter. |
status | query | no | string | enum=queued, running, cancelling, done, failed, cancelled; default="" | Optional operation status filter. |
limit | query | no | integer | format=int32; default=25 | Maximum operations to return. |
offset | query | no | integer | format=int32; default=0 | Number of operations to skip. |
Success response: HTTP 200 — knowledgeBaseEnhancementOperationList.
Response fields: total (integer), operations (array).
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations
Queue a content enhancement operation for stored documents
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
kind | body | no | string | enum=enhance, clear; default="enhance" | Operation kind. enhance re-runs keyword, question, and metadata extraction on stored chunks; clear removes existing enhancement results. |
scope | body | no | string | enum=knowledgebase, document; default="knowledgeBase" | Operation scope. |
documentIds | body | no | array[string] | default=[] | Document IDs for document-scoped operations. |
config | body | no | object | default=[] | One-shot configuration overrides merged over the inherited keyword/question/metadata settings. Never persisted back to the knowledge base. |
force | body | no | boolean | default=false | Cancel a different active enhancement operation before queuing this one. |
onlyMissing | body | no | boolean | default=false | With kind=enhance, skip documents that already have results for every enabled extractor instead of re-running them. |
idempotencyKey | body | yes | string | — | Stable key used to deduplicate retries. |
retryOf | body | no | string | — | Previous failed or cancelled enhancement operation to retry. |
versionId | body | no | string | — | Optional Knowledge Base DRAFT knowledge-base version ID for an ACTIVE Knowledge Base. |
Success response: HTTP 202 — knowledgeBaseEnhancementOperation.
Response fields: $id (string), $createdAt (string), $updatedAt (string), knowledgeBaseId (string), versionId (string), kind (string), scope (string), documentIds (array), criteria (object), status (string), stage (string), message (string), effectiveConfig (object), configHash (string), retryOf (string), stats (object), error (object), logTail (string), startedAt (string), heartbeatAt (string), finishedAt (string).
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId}
Get a Knowledge Base content enhancement operation
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
operationId | path | yes | string | — | Enhancement operation ID. |
Success response: HTTP 200 — knowledgeBaseEnhancementOperation.
Response fields: $id (string), $createdAt (string), $updatedAt (string), knowledgeBaseId (string), versionId (string), kind (string), scope (string), documentIds (array), criteria (object), status (string), stage (string), message (string), effectiveConfig (object), configHash (string), retryOf (string), stats (object), error (object), logTail (string), startedAt (string), heartbeatAt (string), finishedAt (string).
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId}/cancel
Request cancellation of a Knowledge Base content enhancement operation
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
operationId | path | yes | string | — | Enhancement operation ID. |
Success response: HTTP 202 — knowledgeBaseEnhancementOperation.
Response fields: $id (string), $createdAt (string), $updatedAt (string), knowledgeBaseId (string), versionId (string), kind (string), scope (string), documentIds (array), criteria (object), status (string), stage (string), message (string), effectiveConfig (object), configHash (string), retryOf (string), stats (object), error (object), logTail (string), startedAt (string), heartbeatAt (string), finishedAt (string).
GET /knowledgebases/{knowledgeBaseId}/graph
Browse the active GraphRAG node-link graph
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
query | query | no | string | default="" | Optional entity text filter. |
type | query | no | string | default="" | Optional entity type filter. |
community | query | no | string | default="" | Optional community filter. |
seed | query | no | string | default="" | Optional entity seed for bounded N-hop expansion. |
hops | query | no | integer | format=int32; default=1 | Number of neighbor hops when seed is present. |
limit | query | no | integer | format=int32; default=100 | Maximum nodes to return. |
cursor | query | no | string | default="" | Opaque cursor returned by the previous graph page. |
entityScope | query | no | string | enum=core, all; default="core" | Entity scope: "core" shows entities appearing across multiple documents (subsystem-level view), "all" shows every indexed entity. |
documentId | query | no | string | — | Optional Knowledge Base document ID. When set, returns only entities attributed to this document (reverse lookup from the document detail page). |
documentTag | query | no | string | — | Optional tag {subProductId}_{sectionCode}_{fileKey} or multiple comma-separated tags (any-match); free-form values are also accepted.. Combine with documentId to require both. |
subProductId | query | no | string | — | Optional sub-product code. Returns only entities attributed to documents of this sub-product. Combine with documentTag to require both. |
versionId | query | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version for ACTIVE Knowledge Bases. |
view | query | no | string | enum=entities, communities, community; default="entities" | Graph view. Communities returns the lightweight overview; community pages its members and incident edges. Community views require entityScope=all and do not accept entity or document filters. |
communityIds | query | no | array[string] | — | Optional batch of 1-8 unique visualization community IDs for view=community and entityScope=all. Mutually exclusive with community; cursor is not supported. All members must fit in min(limit,100) nodes or the request returns 400. Discover support through visualization.member_batch_version=1. |
Success response: HTTP 200 — knowledgeBaseGraph.
Response fields: resultGeneration (string), versionId (string), graph (object), totalNodes (integer), hasMore (boolean), nextCursor (string), truncated (boolean).
POST /knowledgebases/{knowledgeBaseId}/graph/search
Retrieve GraphRAG context for a question in one Knowledge Base
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
query | body | yes | string | — | Question to retrieve GraphRAG context for. |
maxToken | body | no | integer | format=int32; default=8196 | Maximum graph context tokens. |
entityTopN | body | no | integer | format=int32; default=6 | Maximum matching entities. |
relationTopN | body | no | integer | format=int32; default=6 | Maximum matching relations. |
communityTopN | body | no | integer | format=int32; default=1 | Maximum community reports. |
entitySimilarityThreshold | body | no | number | format=float; default=0.3 | Minimum entity similarity. |
relationSimilarityThreshold | body | no | number | format=float; default=0.3 | Minimum relation similarity. |
versionId | body | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version. |
Success response: HTTP 200 — knowledgeBaseGraphSearch.
Response fields: resultGeneration (string), versionId (string), content (string), graphContext (object).
GET /knowledgebases/{knowledgeBaseId}/lexicons
getKnowledgeBaseBindings
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | knowledgeBaseId |
Success response: HTTP 200 — lexiconBindings.
Response fields: enabled (boolean), stopIntercept (boolean), stopReply (string), bindings (object).
PUT /knowledgebases/{knowledgeBaseId}/lexicons
updateKnowledgeBaseBindings
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | knowledgeBaseId |
bindings | body | yes | array[array] | — | bindings |
enabled | body | no | boolean | default=false | enabled |
Success response: HTTP 200 — lexiconBindings.
Response fields: enabled (boolean), stopIntercept (boolean), stopReply (string), bindings (object).
POST /knowledgebases/{knowledgeBaseId}/search
Search knowledge base
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
query | body | yes | string | — | Search query text. |
limit | body | no | integer | format=int32; default=10 | Final number of results to return. |
searchMode | body | no | string | enum=vector, fulltext, hybrid; default="hybrid" | Search mode: vector, fulltext, or hybrid. |
rerank | body | no | boolean | default=false | Whether to rerank recall results via LLM Gateway. |
recallLimit | body | no | integer | format=int32 | Recall width when rerank is enabled. Defaults to max(limit×4, 20). |
rerankModel | body | no | string | default="" | Optional explicit rerank model ID. Overrides automatic provider selection when rerank is enabled. |
rerankProviderRef | body | no | string | — | Pinned rerank provider source as project:<providerId> or trial:<bindingId>. Omit to use automatic routing. Do not use providerType:providerId. |
similarityThreshold | body | no | number | format=float | Minimum vector similarity. Supported by vector search and the vector recall branch of hybrid search. |
vectorWeight | body | no | number | format=float | Hybrid vector branch weight (fulltext uses 1 - vectorWeight). Defaults to knowledge base retrievalDefaults.vectorWeight. |
useKnowledgeGraph | body | no | boolean | default=false | Whether to add active GraphRAG retrieval. |
useWiki | body | no | boolean | default=false | Whether to add active Wiki retrieval. |
graphOptions | body | no | object | default=[] | Bounded GraphRAG retrieval options. |
wikiOptions | body | no | object | default=[] | Wiki mode, topK, minK, vector, and bounded link expansion options. |
allowDegraded | body | no | boolean | default=true | Whether enhanced capability failures may return ordinary results with explicit degradation metadata. |
answer | body | no | boolean | default=false | Whether to synthesize a grounded answer from merged retrieval evidence. Uses the knowledge base indexingDefaults chat model. |
documentTag | body | no | string | — | Optional tag {subProductId}_{sectionCode}_{fileKey} or multiple comma-separated tags (any-match); free-form values are also accepted.. Restricts chunk, GraphRAG, and Wiki recall. |
subProductId | body | no | string | — | Optional sub-product code. Restricts chunk, GraphRAG, and Wiki recall to documents of this sub-product (metadata.subProductId or the documentTag segment). |
projectId | body | no | string | — | Optional customer project identifier. Restricts recall to documents carrying metadata.projectId of this project (shared-library layout 6.2 option B). |
metadataFilter | body | no | object | default={} | Optional document metadata filter. Matching documents are selected before chunk recall, so other documents' chunks are excluded. |
applyLexicon | body | no | boolean | — | Override lexicon rewriting for this search only. Omit to use knowledge base settings. |
documentIds | body | no | array[string] | — | Optional list of 1 to 100 unique document IDs. Restricts base RAG recall to those documents; cannot be combined with GraphRAG or Wiki retrieval. |
versionId | body | no | string | — | Optional Version ID. Defaults to the current READY Version when Versioning is active. |
Success response: HTTP 200 — knowledgeBaseSearchResultList.
Response fields: stopped (boolean), effectiveQuery (string), stopReply (string), total (integer), results (array), reranked (boolean), resolvedVersionId (string), capabilities (object), degradedCapabilities (array), answer (object), elapsedMs (integer), timingMs (object).
GET /knowledgebases/{knowledgeBaseId}/wiki/graph
Get the canonical Wiki page-link graph including red links
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
versionId | query | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version for ACTIVE Knowledge Bases. |
documentTag | query | no | string | — | Optional tag {subProductId}_{sectionCode}_{fileKey} or multiple comma-separated tags (any-match); free-form values are also accepted. Returns only Wiki pages whose sourceChunks provenance cites a matching document; links become the induced subgraph on the retained pages. |
subProductId | query | no | string | — | Optional sub-product code. Returns only Wiki pages whose provenance cites documents of this sub-product. Combine with documentTag to require both. |
Success response: HTTP 200 — knowledgeBaseWikiGraph.
Response fields: versionId (string), pages (array), links (object).
GET /knowledgebases/{knowledgeBaseId}/wiki/pages
List canonical Knowledge Wiki pages
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
pageType | query | no | string | enum=entity, topic, survey, agent_practice, category_index; default="" | Optional Wiki page type. |
status | query | no | string | enum=draft, published, conflict, archived; default="" | Optional Wiki page status. |
limit | query | no | integer | format=int32; default=50 | Maximum pages to return. |
offset | query | no | integer | format=int32; default=0 | Number of pages to skip. |
versionId | query | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version for ACTIVE Knowledge Bases. |
documentTag | query | no | string | — | Optional tag {subProductId}_{sectionCode}_{fileKey} or multiple comma-separated tags (any-match); free-form values are also accepted. Returns only Wiki pages whose sourceChunks provenance cites a matching document. |
subProductId | query | no | string | — | Optional sub-product code. Returns only Wiki pages whose provenance cites documents of this sub-product. Combine with documentTag to require both. |
Success response: HTTP 200 — knowledgeBaseWikiPageList.
Response fields: total (integer), pages (array).
POST /knowledgebases/{knowledgeBaseId}/wiki/search
Search Wiki pages in one Knowledge Base
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
knowledgeBaseId | path | yes | string | — | Knowledge base ID. |
query | body | yes | string | — | Wiki query text. |
searchMode | body | no | string | enum=auto, wiki_direct, wiki_retrieved, rag_first; default="auto" | Wiki router tier override. |
topK | body | no | integer | format=int32; default=8 | Maximum Wiki pages to return. |
useVector | body | no | boolean | default=true | Whether to include vector recall. |
vectorWeight | body | no | number | format=float; default=0.4 | Vector contribution before RRF. |
linkOptions | body | no | object | default=[] | Bounded Wiki link expansion options. |
versionId | body | no | string | — | Optional Knowledge Base Version ID. Defaults to the current Version. |
Success response: HTTP 200 — knowledgeBaseWikiSearch.
Response fields: resultGeneration (string), contentStale (boolean), tier (string), results (array), toc (object), categoryIndex (object), latencyMs (integer).
GET /lexicons
list
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
limit | query | no | integer | format=int32; default=25 | limit |
offset | query | no | integer | format=int32; default=0 | offset |
Success response: HTTP 200 — lexiconList.
Response fields: total (integer), lexicons (array).
POST /lexicons
create
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | body | no | string | default="unique()" | lexiconId |
name | body | yes | string | — | name |
description | body | no | string | default="" | description |
permissions | body | no | array[string] | — | permissions |
synonymRewriteMode | body | no | string | enum=matched, primary, primary_expansion; default="matched" | Synonym rewriting: matched, primary, or primary_expansion. |
Success response: HTTP 201 — lexicon.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), description (string), tokenizerProfile (string), synonymRewriteMode (string), revision (integer).
GET /lexicons/{lexiconId}
get
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
Success response: HTTP 200 — lexicon.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), description (string), tokenizerProfile (string), synonymRewriteMode (string), revision (integer).
PATCH /lexicons/{lexiconId}
update
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
name | body | no | string | — | name |
description | body | no | string | — | description |
permissions | body | no | array[string] | — | permissions |
synonymRewriteMode | body | no | string | enum=matched, primary, primary_expansion | Synonym rewriting: matched, primary, or primary_expansion. |
Success response: HTTP 200 — lexicon.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), description (string), tokenizerProfile (string), synonymRewriteMode (string), revision (integer).
DELETE /lexicons/{lexiconId}
delete
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
Success response: HTTP 204 — No content.
GET /lexicons/{lexiconId}/entries
listEntries
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
limit | query | no | integer | format=int32; default=25 | Page size. |
offset | query | no | integer | format=int32; default=0 | Page offset. |
entryType | query | no | string | enum=synonym, expansion, stop | Filter entries by rule type. Omit to list all types. |
Success response: HTTP 200 — lexiconEntryList.
Response fields: total (integer), entries (array).
POST /lexicons/{lexiconId}/entries
createEntry
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
entryId | body | no | string | default="unique()" | entryId |
entryType | body | yes | string | enum=synonym, expansion, stop | entryType |
terms | body | yes | array[string] | — | terms |
expansions | body | no | array[string] | default=[] | expansions |
position | body | no | integer | format=int32; default=0 | position |
Success response: HTTP 201 — lexiconEntry.
Response fields: $id (string), $createdAt (string), $updatedAt (string), lexiconId (string), entryType (string), terms (array), expansions (array), position (integer).
GET /lexicons/{lexiconId}/entries/{entryId}
getEntry
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
entryId | path | yes | string | — | entryId |
Success response: HTTP 200 — lexiconEntry.
Response fields: $id (string), $createdAt (string), $updatedAt (string), lexiconId (string), entryType (string), terms (array), expansions (array), position (integer).
PATCH /lexicons/{lexiconId}/entries/{entryId}
updateEntry
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
entryId | path | yes | string | — | entryId |
entryType | body | no | string | enum=synonym, expansion, stop | entryType |
terms | body | no | array[string] | — | terms |
expansions | body | no | array[string] | — | expansions |
position | body | no | integer | format=int32 | position |
Success response: HTTP 200 — lexiconEntry.
Response fields: $id (string), $createdAt (string), $updatedAt (string), lexiconId (string), entryType (string), terms (array), expansions (array), position (integer).
DELETE /lexicons/{lexiconId}/entries/{entryId}
deleteEntry
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
entryId | path | yes | string | — | entryId |
Success response: HTTP 204 — No content.
GET /lexicons/{lexiconId}/export
export
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | Lexicon ID. |
format | query | no | string | enum=json, csv, xlsx; default="json" | Export format. |
Success response: HTTP 200 — File.
POST /lexicons/{lexiconId}/import
import
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
entries | body | no | array[array] | default=[] | entries |
mode | body | no | string | enum=merge, overwrite; default="merge" | mode |
dryRun | body | no | boolean | default=true | dryRun |
format | body | no | string | enum=json, csv, xlsx; default="json" | File format. |
content | body | no | string | default="" | Base64 file content for CSV/XLSX. |
Success response: HTTP 200 — lexiconImport.
Response fields: total (integer), inserted (integer), skipped (integer), errors (object), rows (object), applied (boolean), tokenizerProfile (string), tokenizationChanged (boolean).
POST /lexicons/{lexiconId}/preview
preview
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
query | body | yes | string | — | query |
Success response: HTTP 200 — lexiconRewrite.
Response fields: original (string), rewritten (string), stopped (boolean), stopMatched (array), mappings (object), tokenizerProfile (string), queryTokens (array).
GET /lexicons/{lexiconId}/references
listReferences
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
lexiconId | path | yes | string | — | lexiconId |
Success response: HTTP 200 — lexiconReferences.
Response fields: total (integer), references (object).
Errors and retries
400/422: check types, enumerations and rules. 401/403: verify identity and scopes; dataset analyses additionally require trace and dataset read access. 404: check that the resource exists in the current project. 409: read current state before deciding to retry. 429: honor Retry-After. After 5xx or network loss, inspect operation state first. Preserve an idempotency key across retries; change it only for a deliberate new operation. Confirm deletion and clearing targets before writing.