API文档：Outline RESTful接口详解-优快云博客

API文档：Outline RESTful接口详解

【免费下载链接】outline Outline 是一个基于 React 和 Node.js 打造的快速、协作式团队知识库。它可以让团队方便地存储和管理知识信息。你可以直接使用其托管版本，也可以自己运行或参与开发。源项目地址：https://github.com/outline/outline 项目地址: https://gitcode.com/GitHub_Trending/ou/outline

1. 接口概述

Outline提供了一套完整的RESTful API（Application Programming Interface，应用程序编程接口），允许开发者与Outline团队知识库进行交互。通过这些接口，可以实现文档的创建、查询、更新、删除等核心操作，为集成Outline到第三方系统或构建自定义工具提供了灵活的途径。

1.1 接口基础信息

项目	说明
基础URL	`/api`
认证方式	JWT（JSON Web Token）
请求格式	JSON
响应格式	JSON
状态码	遵循HTTP标准状态码

1.2 通用响应结构

所有API接口返回的响应都遵循以下基本结构：

{
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 100
  },
  "data": [],
  "policies": {}
}

其中：

pagination：分页信息，仅在返回列表数据时包含
data：接口返回的具体数据
policies：权限信息，描述当前用户对返回资源的操作权限

2. 文档管理接口

2.1 获取文档列表

请求

接口地址：POST /api/documents.list
认证要求：需要认证
请求体参数：

{
  "sort": "updatedAt",
  "direction": "DESC",
  "userId": "uuid",
  "collectionId": "uuid",
  "backlinkDocumentId": "uuid",
  "parentDocumentId": "uuid",
  "template": false,
  "statusFilter": ["published", "draft"]
}

参数说明：

参数名	类型	描述
sort	string	排序字段，可选值：createdAt, updatedAt, publishedAt, index, title
direction	string	排序方向，可选值：ASC, DESC
userId	string	创建者ID，用于筛选特定用户创建的文档
collectionId	string	集合ID，用于筛选特定集合下的文档
backlinkDocumentId	string	反向链接文档ID，用于筛选引用了指定文档的文档
parentDocumentId	string	父文档ID，用于筛选特定父文档下的子文档
template	boolean	是否为模板文档
statusFilter	array	状态筛选，可选值：published, draft, archived

响应

{
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 100
  },
  "data": [
    {
      "id": "uuid",
      "title": "文档标题",
      "text": "文档内容",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z",
      "publishedAt": "2025-01-01T00:00:00Z",
      "collectionId": "uuid",
      "parentDocumentId": "uuid",
      "createdBy": {
        "id": "uuid",
        "name": "用户名"
      },
      "icon": "file-text",
      "color": "#000000",
      "isTemplate": false,
      "isArchived": false,
      "isDeleted": false
    }
  ],
  "policies": {
    "uuid": {
      "canRead": true,
      "canUpdate": true,
      "canDelete": true
    }
  }
}

示例代码

fetch('/api/documents.list', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    sort: 'updatedAt',
    direction: 'DESC',
    collectionId: 'your-collection-id'
  })
})
.then(response => response.json())
.then(data => console.log(data));

2.2 创建文档

请求

接口地址：POST /api/documents.create
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "title": "文档标题",
  "text": "文档内容",
  "icon": "file-text",
  "color": "#000000",
  "publish": true,
  "collectionId": "uuid",
  "parentDocumentId": "uuid",
  "templateId": "uuid",
  "createdAt": "2025-01-01T00:00:00Z",
  "fullWidth": false,
  "template": false
}

参数说明：

参数名	类型	描述
id	string	文档ID，可选，不提供则自动生成
title	string	文档标题
text	string	文档内容，使用ProseMirror JSON格式
icon	string	文档图标
color	string	图标颜色，十六进制格式
publish	boolean	是否发布
collectionId	string	所属集合ID
parentDocumentId	string	父文档ID
templateId	string	模板ID，用于基于模板创建文档
createdAt	string	创建时间，可选，默认为当前时间
fullWidth	boolean	是否全屏显示
template	boolean	是否为模板文档

响应

{
  "data": {
    "id": "uuid",
    "title": "文档标题",
    "text": "文档内容",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z",
    "publishedAt": "2025-01-01T00:00:00Z",
    "collectionId": "uuid",
    "parentDocumentId": "uuid",
    "createdBy": {
      "id": "uuid",
      "name": "用户名"
    },
    "icon": "file-text",
    "color": "#000000",
    "isTemplate": false,
    "isArchived": false,
    "isDeleted": false
  },
  "policies": {
    "canRead": true,
    "canUpdate": true,
    "canDelete": true
  }
}

2.3 获取文档详情

请求

接口地址：POST /api/documents.info
认证要求：需要认证或通过共享链接访问
请求体参数：

{
  "id": "uuid",
  "shareId": "string",
  "apiVersion": 2
}

参数说明：

参数名	类型	描述
id	string	文档ID
shareId	string	共享链接ID，用于通过共享链接访问文档
apiVersion	number	API版本，可选值：1, 2

响应

{
  "data": {
    "document": {
      "id": "uuid",
      "title": "文档标题",
      "text": "文档内容",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z",
      "publishedAt": "2025-01-01T00:00:00Z",
      "collectionId": "uuid",
      "parentDocumentId": "uuid",
      "createdBy": {
        "id": "uuid",
        "name": "用户名"
      },
      "icon": "file-text",
      "color": "#000000",
      "isTemplate": false,
      "isArchived": false,
      "isDeleted": false,
      "revisions": [],
      "comments": [],
      "attachments": []
    }
  },
  "policies": {
    "canRead": true,
    "canUpdate": true,
    "canDelete": true
  }
}

2.4 更新文档

请求

接口地址：POST /api/documents.update
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "title": "新文档标题",
  "text": "新文档内容",
  "icon": "file-text",
  "color": "#000000",
  "fullWidth": false,
  "insightsEnabled": true,
  "publish": true,
  "templateId": "uuid",
  "collectionId": "uuid",
  "append": false,
  "done": true
}

参数说明：

参数名	类型	描述
id	string	文档ID，必需
title	string	新文档标题
text	string	新文档内容
icon	string	文档图标
color	string	图标颜色
fullWidth	boolean	是否全屏显示
insightsEnabled	boolean	是否启用洞察功能
publish	boolean	是否发布
templateId	string	模板ID
collectionId	string	所属集合ID
append	boolean	是否追加内容
done	boolean	编辑会话是否完成

响应

{
  "data": {
    "id": "uuid",
    "title": "新文档标题",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

2.5 删除文档

请求

接口地址：POST /api/documents.delete
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "permanent": false
}

参数说明：

参数名	类型	描述
id	string	文档ID，必需
permanent	boolean	是否永久删除，默认为false（放入回收站）

响应

{
  "data": {
    "id": "uuid",
    "deletedAt": "2025-01-01T00:00:00Z"
  }
}

3. 文档状态管理

3.1 归档文档

请求

接口地址：POST /api/documents.archive
认证要求：需要认证
请求体参数：

{
  "id": "uuid"
}

响应

{
  "data": {
    "id": "uuid",
    "archivedAt": "2025-01-01T00:00:00Z"
  }
}

3.2 恢复文档

请求

接口地址：POST /api/documents.restore
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "collectionId": "uuid",
  "revisionId": "uuid"
}

参数说明：

参数名	类型	描述
id	string	文档ID，必需
collectionId	string	恢复到的集合ID
revisionId	string	恢复到的版本ID

响应

{
  "data": {
    "id": "uuid",
    "deletedAt": null,
    "archivedAt": null
  }
}

3.3 取消发布文档

请求

接口地址：POST /api/documents.unpublish
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "detach": false
}

参数说明：

参数名	类型	描述
id	string	文档ID，必需
detach	boolean	是否从集合中分离

响应

{
  "data": {
    "id": "uuid",
    "publishedAt": null
  }
}

4. 文档操作接口

4.1 复制文档

请求

接口地址：POST /api/documents.duplicate
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "title": "新文档标题",
  "recursive": false,
  "publish": false,
  "collectionId": "uuid",
  "parentDocumentId": "uuid"
}

参数说明：

参数名	类型	描述
id	string	源文档ID，必需
title	string	新文档标题
recursive	boolean	是否递归复制子文档
publish	boolean	是否发布新文档
collectionId	string	新文档所属集合ID
parentDocumentId	string	新文档父文档ID

响应

{
  "data": {
    "id": "new-uuid",
    "title": "新文档标题"
  }
}

4.2 移动文档

请求

接口地址：POST /api/documents.move
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "collectionId": "uuid",
  "parentDocumentId": "uuid",
  "index": 0
}

参数说明：

参数名	类型	描述
id	string	文档ID，必需
collectionId	string	目标集合ID
parentDocumentId	string	目标父文档ID
index	number	在父文档中的位置索引

响应

{
  "data": {
    "id": "uuid",
    "collectionId": "new-collection-uuid",
    "parentDocumentId": "new-parent-uuid"
  }
}

4.3 导出文档

请求

接口地址：POST /api/documents.export
认证要求：需要认证
请求体参数：

{
  "id": "uuid"
}

响应

响应为文件下载，根据Accept请求头的不同，支持以下格式：

text/html：HTML格式
text/markdown：Markdown格式
application/pdf：PDF格式（仅企业版支持）

4.4 导入文档

请求

接口地址：POST /api/documents.import
认证要求：需要认证
请求体：multipart/form-data格式，包含要导入的文件
请求参数：

publish=true&collectionId=uuid&parentDocumentId=uuid

参数说明：

参数名	类型	描述
publish	boolean	是否发布导入的文档
collectionId	string	导入到的集合ID
parentDocumentId	string	导入到的父文档ID

响应

{
  "data": {
    "taskId": "uuid",
    "status": "processing"
  }
}

5. 文档搜索接口

5.1 搜索文档标题

请求

接口地址：POST /api/documents.search_titles
认证要求：需要认证
请求体参数：

{
  "query": "搜索关键词",
  "collectionId": "uuid",
  "userId": "uuid",
  "dateFilter": "month",
  "statusFilter": ["published"],
  "snippetMinWords": 20,
  "snippetMaxWords": 30
}

参数说明：

参数名	类型	描述
query	string	搜索关键词，必需
collectionId	string	集合ID
userId	string	创建者ID
dateFilter	string	日期筛选，可选值：day, week, month, year
statusFilter	array	状态筛选
snippetMinWords	number	摘要最小单词数
snippetMaxWords	number	摘要最大单词数

响应

{
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 10
  },
  "data": [],
  "policies": {}
}

5.2 搜索文档内容

请求

接口地址：POST /api/documents.search
认证要求：需要认证或通过共享链接访问
请求体参数：

{
  "query": "搜索关键词",
  "collectionId": "uuid",
  "documentId": "uuid",
  "userId": "uuid",
  "dateFilter": "month",
  "statusFilter": ["published"],
  "shareId": "string",
  "snippetMinWords": 20,
  "snippetMaxWords": 30
}

参数说明与搜索文档标题接口类似，增加了：

参数名	类型	描述
documentId	string	文档ID，用于搜索特定文档内的内容
shareId	string	共享链接ID，用于通过共享链接搜索

响应

响应结构与搜索文档标题接口相同，但data字段会包含匹配的内容摘要。

6. 文档权限管理

6.1 添加用户权限

请求

接口地址：POST /api/documents.add_user
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "userId": "uuid",
  "permission": "read_write"
}

参数说明：

参数名	类型	描述
id	string	文档ID，必需
userId	string	用户ID，必需
permission	string	权限级别，可选值：read, read_write, admin

响应

{
  "data": {
    "documentId": "uuid",
    "userId": "uuid",
    "permission": "read_write"
  }
}

6.2 移除用户权限

请求

接口地址：POST /api/documents.remove_user
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "userId": "uuid"
}

响应

{
  "data": {
    "success": true
  }
}

6.3 添加组权限

请求

接口地址：POST /api/documents.add_group
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "groupId": "uuid",
  "permission": "read_write"
}

参数说明：

参数名	类型	描述
id	string	文档ID，必需
groupId	string	组ID，必需
permission	string	权限级别，可选值：read, read_write, admin

响应

{
  "data": {
    "documentId": "uuid",
    "groupId": "uuid",
    "permission": "read_write"
  }
}

6.4 移除组权限

请求

接口地址：POST /api/documents.remove_group
认证要求：需要认证
请求体参数：

{
  "id": "uuid",
  "groupId": "uuid"
}

响应

{
  "data": {
    "success": true
  }
}

7. 错误处理

7.1 常见错误状态码

状态码	描述
400	请求参数错误
401	未授权，需要认证
403	权限不足
404	资源不存在
422	验证错误
500	服务器内部错误

7.2 错误响应格式

{
  "error": {
    "name": "ValidationError",
    "message": "Invalid input provided",
    "status": 422,
    "details": [
      {
        "path": ["title"],
        "message": "Title is required"
      }
    ]
  }
}

8. 接口调用流程示例

以下是一个完整的文档创建和更新流程示例：

// 1. 获取JWT令牌
const token = await getAuthToken();

// 2. 创建文档
const createResponse = await fetch('/api/documents.create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    title: '新文档',
    text: '这是一个新文档',
    collectionId: 'collection-uuid',
    publish: true
  })
});
const { data: newDocument } = await createResponse.json();

// 3. 更新文档
const updateResponse = await fetch('/api/documents.update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    id: newDocument.id,
    title: '更新后的文档标题',
    text: '更新后的文档内容'
  })
});
const { data: updatedDocument } = await updateResponse.json();

// 4. 获取文档详情
const infoResponse = await fetch('/api/documents.info', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    id: updatedDocument.id
  })
});
const { data: documentDetails } = await infoResponse.json();

9. 接口调用频率限制

为了保护系统稳定性，API接口有调用频率限制：

普通接口：每分钟25次
搜索接口：每分钟100次

当超过限制时，接口将返回429状态码。

10. 总结

本文档详细介绍了Outline RESTful API的文档管理相关接口，包括文档的CRUD操作、状态管理、权限控制等。通过这些接口，开发者可以方便地与Outline系统进行集成，实现自定义的文档管理功能。

如需了解更多接口详情，请参考Outline源代码中的路由定义文件。

mermaid

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考