Docs
文档目录

场景库 API

场景库保存业务场景名称、定义和有序分类路径,供知识图谱与 Wiki 组织使用。

资源与基础路径

Base URL 使用实例 endpoint 的 /v1,资源包括场景、分类与导入预览。场景包含名称、定义、有序分类路径与 revision;分类知识绑定不继承父分类,删除分类前需要影响预览 token。修改成功后读取新 revision,HTTP 201 仅说明保存,不表示后续知识索引已构建。

认证与权限

scenarios.read 允许读取和预览;scenarios.write 用于创建、编辑、导入与删除。Header 携带项目身份与项目 Key,不能把 Console 组织身份替代成其他项目 Key。本文只覆盖项目范围。

端点清单

以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。

HTTPScopeSDK
GET /scenariosscenarios.readscenarios.list
POST /scenariosscenarios.writescenarios.create
GET /scenarios/categoriesscenarios.readscenarios.listCategories
POST /scenarios/categoriesscenarios.writescenarios.createCategory
DELETE /scenarios/categories/{categoryId}scenarios.writescenarios.deleteCategory
GET /scenarios/categories/{categoryId}/deletionscenarios.readscenarios.getCategoryDeletionImpact
PATCH /scenarios/categories/{categoryId}/knowledge-bindingscenarios.writescenarios.updateKnowledgeBinding
PATCH /scenarios/categories/{categoryId}/namescenarios.writescenarios.renameCategory
POST /scenarios/importscenarios.writescenarios.import
POST /scenarios/import/parsescenarios.readscenarios.parseImport
POST /scenarios/import/previewscenarios.readscenarios.previewImport
GET /scenarios/{scenarioId}scenarios.readscenarios.get
PATCH /scenarios/{scenarioId}scenarios.writescenarios.update
DELETE /scenarios/{scenarioId}scenarios.writescenarios.delete

请求与响应

GET /scenarios

list

参数位置必填类型约束 / 默认值含义
limitquery否integerformat=int32; default=25分页大小。
offsetquery否integerformat=int32; default=0分页偏移量。
searchquery否stringdefault=""名称包含的文本。
categoriesquery否array[string]default=[]分类路径。
includeDescendantsquery否booleandefault=true是否包含下级分类中的场景。

成功响应:HTTP 200 — scenarioList.

返回字段:total (integer), scenarios (array).

POST /scenarios

create

参数位置必填类型约束 / 默认值含义
scenarioIdbody否stringdefault="unique()"场景 ID。
categoriesbody是array[string]—有序分类路径。
namebody是string—场景名称。
definitionbody否stringdefault=""场景定义。

成功响应:HTTP 201 — scenario.

返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).

GET /scenarios/categories

listCategories

参数位置必填类型约束 / 默认值含义
limitquery否integerformat=int32; default=100分页大小。
offsetquery否integerformat=int32; default=0分页偏移量。

成功响应:HTTP 200 — scenarioCategoryList.

返回字段:total (integer), categories (array).

POST /scenarios/categories

createCategory

参数位置必填类型约束 / 默认值含义
categoriesbody是array[string]—有序分类路径。

成功响应:HTTP 201 — scenarioCategory.

返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).

DELETE /scenarios/categories/{categoryId}

deleteCategory

参数位置必填类型约束 / 默认值含义
categoryIdpath是string—分类 ID。
tokenbody是string—确认删除影响后取得的令牌。

成功响应:HTTP 204 — No content.

GET /scenarios/categories/{categoryId}/deletion

getCategoryDeletionImpact

参数位置必填类型约束 / 默认值含义
categoryIdpath是string—分类 ID。

成功响应:HTTP 200 — scenarioCategoryImpact.

返回字段:token (string), categories (array), scenarios (array).

PATCH /scenarios/categories/{categoryId}/knowledge-binding

updateKnowledgeBinding

参数位置必填类型约束 / 默认值含义
categoryIdpath是string—分类 ID。
revisionbody是integerformat=int32预期的绑定修订号。
knowledgeBaseIdbody否stringdefault=""知识库 ID;留空可解除绑定。
knowledgeTagPathbody否stringdefault=""完整标签目录路径;留空可解除绑定。
knowledgeBindingsbody否array[array]—知识目录绑定列表;空列表解除全部绑定。

成功响应:HTTP 200 — scenarioCategory.

返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).

PATCH /scenarios/categories/{categoryId}/name

renameCategory

参数位置必填类型约束 / 默认值含义
categoryIdpath是string—分类 ID。
revisionbody是integerformat=int32预期的分类修订号。
namebody是string—新的分类名称。

成功响应:HTTP 200 — scenarioCategory.

返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).

POST /scenarios/import

import

参数位置必填类型约束 / 默认值含义
entriesbody是array[object]—需要原子导入的场景。
conflictPolicybody否stringenum=error, skip, overwrite; default="error"路径和名称已存在时的处理方式:拒绝、跳过或覆盖;内容未变化的覆盖会被跳过。

成功响应:HTTP 201 — scenarioImport.

返回字段:total (integer), scenarios (array), created (integer), updated (integer), skipped (integer).

POST /scenarios/import/parse

parseImport

参数位置必填类型约束 / 默认值含义
fileformData是file—CSV、XLS 或 XLSX 场景文件;解析过程不会写入存储或场景。

成功响应:HTTP 200 — scenarioImportFile.

返回字段:sheets (array).

POST /scenarios/import/preview

previewImport

参数位置必填类型约束 / 默认值含义
entriesbody是array[object]—仅供预览、不会写入的场景。
conflictPolicybody否stringenum=skip, overwrite; default="skip"预览跳过或覆盖已有场景的结果;提交导入时会重新检查冲突。

成功响应:HTTP 200 — scenarioImportPreview.

返回字段:total (integer), entries (array), created (integer), updated (integer), skipped (integer).

GET /scenarios/{scenarioId}

get

参数位置必填类型约束 / 默认值含义
scenarioIdpath是string—场景 ID。

成功响应:HTTP 200 — scenario.

返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).

PATCH /scenarios/{scenarioId}

update

参数位置必填类型约束 / 默认值含义
scenarioIdpath是string—场景 ID。
revisionbody是integerformat=int32预期修订号。
categoriesbody否array[string]—有序分类路径。
namebody否string—场景名称。
definitionbody否string—场景定义。

成功响应:HTTP 200 — scenario.

返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).

DELETE /scenarios/{scenarioId}

delete

参数位置必填类型约束 / 默认值含义
scenarioIdpath是string—场景 ID。
revisionbody是integerformat=int32预期修订号。

成功响应:HTTP 204 — No content.

错误与边界

400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。

与 Server SDK 的对应

上述端点表中的 scenarios 对应 Node Scenarios 服务;Python 使用 snake_case,Java/Go 的签名与同版本制品分别核对,不从 Node 参数位置推断。下面请求展示列表读取,环境变量由服务端注入。

(
  set +x
  set -o pipefail
  : "${AGENTBASE_API_KEY:?Set AGENTBASE_API_KEY}"
  builtin printf 'X-Appwrite-Key: %s\n' "${AGENTBASE_API_KEY:?Set AGENTBASE_API_KEY}" | curl --disable --header @- --fail-with-body --get "$AGENTBASE_ENDPOINT/scenarios" \
    -H "X-Appwrite-Project: $AGENTBASE_PROJECT_ID" \
    --data-urlencode "limit=25" --data-urlencode "offset=0"
)

导入 entries 实际为对象数组,每项包含 categories/name/definition。生成 spec 的 array[array] 与 Node TypeScript 的 any[][] 类型过窄;本页按服务端校验器列出真实 JSON 形状,JavaScript 示例直接复用 parseImport 返回的条目。TypeScript 接入需隔离这一类型差异,不把类型断言当作请求已通过验证。