# 下载文档原文件

`GET` `/api/knowledge/document/download`

校验调用方对该文档的访问权限后，生成 OSS 预签名 URL 并以 HTTP 302 重定向到该 URL，由浏览器原生触发下载。API Key / OpenAPI 调用可下载整个应用空间（X-App-Id）内知识库的文档，用户控制台调用可下载该用户自己创建的知识库的文档；文档不存在或越出范围均返回 403（两者不可区分，避免泄露文档是否存在）。预签名 URL 有短期有效期（默认数分钟），过期需重新调用本接口。响应头不附带任何业务数据，请通过 documentId 查询接口获取文件名等元信息。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| documentId | integer | 是 | 文档ID |
| agentId | integer | 否 | 智能体ID，仅用于应用空间授权只读知识库 |

## 响应

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |