替换已上传文件内容

接口说明

替换一个已上传文件的完整 Markdown 正文，并可同时调整路径。

接口信息

字段	值
方法	PUT
路径	/openapi/v2/knowledge-bases/{knowledgeBaseId}/source-files/{sourceFileId}/content
Operation ID	replaceSourceFileContent
鉴权	Bearer OpenAPI key

入参

名称	位置	必填	类型	示例	说明
knowledgeBaseId	path	是	string	knowledge-base-11111111-1111-4111-8111-111111111111	知识库 API 返回的知识库标识。
sourceFileId	path	是	string	source-file-11111111-1111-4111-8111-111111111111	上传接口或已上传文件列表接口返回的文件标识。
Idempotency-Key	header	是	string	mutation-2026-07-10-001	客户端为请求生成的幂等键。重试同一请求时复用相同值，可以避免创建重复任务。
If-Match	header	是	string	"1"	API 返回的当前 resourceRevision。如果读取后资源又被修改，请求会返回冲突，避免覆盖较新的修改。
X-Source-Relative-Path	header	否	string	handbook/setup/install.md	在同一请求中替换并移动文件时使用的新路径。目标目录必须已经存在。

请求体

text/markdown

数据结构: string

用于替换当前文件的完整 Markdown 正文。

请求示例

curl -X PUT "https://openapi.example.com/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111/content" \
  -H "Authorization: Bearer <openapi-key>" \
  -H "Idempotency-Key: mutation-2026-07-10-001" \
  -H "If-Match: \"1\"" \
  -H "X-Source-Relative-Path: handbook/setup/install.md" \
  -H "Content-Type: text/markdown" \
  --data-binary "# Installation\n\nCurrent installation guidance."

成功响应

202

返回已经提交到后台处理的文件正文替换请求。

字段	必填	类型	说明
operation	是	object	资源变更记录。

成功响应示例

{
  "operation": {
    "operationId": "source-replace-44444444-4444-4444-8444-444444444444",
    "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111",
    "kind": "source_file_replace",
    "state": "processing",
    "expectedResourceRevision": 1,
    "targetKind": "source_file",
    "targetId": "source-file-11111111-1111-4111-8111-111111111111",
    "candidateRelativePath": "handbook/setup/install.md",
    "result": null,
    "errorCode": null,
    "retryGuidance": "Check this change again after a short delay.",
    "actions": {
      "self": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/source-replace-44444444-4444-4444-8444-444444444444"
    },
    "createdAt": "2026-06-17T00:00:00.000Z",
    "updatedAt": "2026-06-17T00:00:00.000Z",
    "completedAt": null
  }
}

错误码

下表列出这个接口已声明的全部错误响应。

HTTP 状态	错误码	说明
401	UNAUTHORIZED	Bearer API key 缺失、格式错误、未知、已撤销或已删除。
404	NOT_FOUND	请求的资源不存在。
409	CONFLICT	请求与资源当前状态冲突。
413	PAYLOAD_TOO_LARGE	请求体或待读取文件超过当前接口允许的大小。
422	VALIDATION_ERROR	请求未通过校验。
429	RATE_LIMITED	请求超过当前配置的速率限制。
500	INTERNAL_ERROR	API 遇到内部错误。
503	DATABASE_REPOSITORY_UNAVAILABLE	当前接口所需的数据暂时不可用。

后续操作

• 获取文档索引或资源变更