Outline API开发者指南：构建团队知识管理集成方案

2026-03-12 03:54:57作者：蔡怀权

接口总览

Outline提供了一套功能完备的RESTful API，使开发者能够与团队知识库进行深度集成。无论是构建自定义客户端、自动化工作流，还是与第三方系统对接，这些API都提供了灵活而强大的接口支持。

基础信息

项目	说明
基础URL	`/api`
认证方式	JWT（JSON Web Token）- 一种基于JSON的开放标准，用于在各方之间安全地传输信息
请求/响应格式	JSON（JavaScript Object Notation）
状态码	遵循HTTP标准状态码

通用响应结构

所有API接口返回的响应都遵循一致的结构：

{
  "pagination": {          // 分页信息，仅在返回列表数据时包含
    "offset": 0,           // 当前偏移量
    "limit": 20,           // 每页项目数
    "total": 100           // 总项目数
  },
  "data": [],              // 接口返回的具体数据
  "policies": {}           // 权限信息，描述当前用户对返回资源的操作权限
}

核心功能模块

文档管理

获取文档列表 ✅ 稳定

接口用途：批量获取文档信息，支持多条件筛选和排序，适用于实现文档列表展示、批量操作等功能。

业务应用场景：团队知识库首页展示、特定集合文档列表、用户创建文档管理页面等。

基础用法

Python示例：

import requests
import json

def get_documents(token, collection_id=None):
    url = "/api/documents.list"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    payload = {
        "sort": "updatedAt",
        "direction": "DESC"
    }
    
    if collection_id:
        payload["collectionId"] = collection_id
        
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    return response.json()

Java示例：

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;
import com.fasterxml.jackson.databind.ObjectMapper;

public class DocumentClient {
    private final String baseUrl = "/api";
    private final String token;
    private final RestTemplate restTemplate;
    private final ObjectMapper objectMapper;
    
    public DocumentClient(String token) {
        this.token = token;
        this.restTemplate = new RestTemplate();
        this.objectMapper = new ObjectMapper();
    }
    
    public Object getDocuments(String collectionId) throws Exception {
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Authorization", "Bearer " + token);
        
        String url = baseUrl + "/documents.list";
        
        // 构建请求体
        StringBuilder payload = new StringBuilder();
        payload.append("{\"sort\":\"updatedAt\", \"direction\":\"DESC\"");
        if (collectionId != null && !collectionId.isEmpty()) {
            payload.append(", \"collectionId\":\"").append(collectionId).append("\"");
        }
        payload.append("}");
        
        HttpEntity<String> request = new HttpEntity<>(payload.toString(), headers);
        ResponseEntity<String> response = restTemplate.postForEntity(url, request, String.class);
        
        return objectMapper.readValue(response.getBody(), Object.class);
    }
}

参数解析

展开查看参数详情

参数名	类型	描述	使用建议
sort	string	排序字段	推荐使用"updatedAt"作为默认排序字段，符合用户对最新内容的关注需求
direction	string	排序方向	可选值：ASC（升序）, DESC（降序），默认使用DESC
userId	string	创建者ID	用于筛选特定用户创建的文档，在个人文档管理场景中使用
collectionId	string	集合ID	必选参数，大多数情况下应指定集合ID以缩小范围
backlinkDocumentId	string	反向链接文档ID	用于查找引用了指定文档的所有文档，实现关联文档推荐
parentDocumentId	string	父文档ID	用于获取子文档列表，实现文档层级结构展示
template	boolean	是否为模板文档	筛选模板文档时使用，单独管理模板资源
statusFilter	array	状态筛选	可选值：published, draft, archived，默认为["published"]

响应示例

{
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 100
  },
  "data": [
    {
      "id": "uuid",                  // 文档唯一标识符
      "title": "文档标题",            // 文档标题
      "text": "文档内容",            // 文档内容，ProseMirror JSON格式
      "createdAt": "2025-01-01T00:00:00Z",  // 创建时间
      "updatedAt": "2025-01-01T00:00:00Z",  // 更新时间
      "publishedAt": "2025-01-01T00:00:00Z", // 发布时间
      "collectionId": "uuid",        // 所属集合ID
      "parentDocumentId": "uuid",    // 父文档ID，若无则为null
      "createdBy": {                 // 创建者信息
        "id": "uuid",
        "name": "用户名"
      },
      "icon": "file-text",           // 文档图标
      "color": "#000000",            // 图标颜色
      "isTemplate": false,           // 是否为模板文档
      "isArchived": false,           // 是否已归档
      "isDeleted": false             // 是否已删除（放入回收站）
    }
  ],
  "policies": {                      // 权限策略
    "uuid": {
      "canRead": true,               // 可读权限
      "canUpdate": true,             // 可更新权限
      "canDelete": true              // 可删除权限
    }
  }
}

创建文档 ✅ 稳定

接口用途：在Outline中创建新文档，支持基于模板创建、指定文档位置等功能。

业务应用场景：用户创建新文档、系统自动生成报告、基于模板快速创建标准化文档等。

基础用法

Python示例：

def create_document(token, title, collection_id, text="", parent_id=None, is_template=False):
    url = "/api/documents.create"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    
    payload = {
        "title": title,
        "text": text,
        "collectionId": collection_id,
        "publish": True,
        "template": is_template
    }
    
    if parent_id:
        payload["parentDocumentId"] = parent_id
        
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    return response.json()

Java示例：

public Object createDocument(String title, String collectionId, String text, 
                            String parentId, boolean isTemplate) throws Exception {
    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_JSON);
    headers.set("Authorization", "Bearer " + token);
    
    String url = baseUrl + "/documents.create";
    
    // 构建请求体
    StringBuilder payload = new StringBuilder();
    payload.append("{\"title\":\"").append(title).append("\",");
    payload.append("\"text\":\"").append(text).append("\",");
    payload.append("\"collectionId\":\"").append(collectionId).append("\",");
    payload.append("\"publish\":true,");
    payload.append("\"template\":").append(isTemplate);
    
    if (parentId != null && !parentId.isEmpty()) {
        payload.append(",\"parentDocumentId\":\"").append(parentId).append("\"");
    }
    
    payload.append("}");
    
    HttpEntity<String> request = new HttpEntity<>(payload.toString(), headers);
    ResponseEntity<String> response = restTemplate.postForEntity(url, request, String.class);
    
    return objectMapper.readValue(response.getBody(), Object.class);
}

参数解析

展开查看参数详情

参数名	类型	描述	使用建议
id	string	文档ID	可选，不提供则自动生成，建议由系统自动生成UUID
title	string	文档标题	必需，建议控制在100字符以内，清晰描述文档内容
text	string	文档内容	使用ProseMirror JSON格式，可先构建基础结构再填充内容
icon	string	文档图标	选择与文档内容相关的图标，增强视觉识别性
color	string	图标颜色	十六进制格式，建议使用系统预设色板
publish	boolean	是否发布	默认为true，创建后直接发布；草稿设为false
collectionId	string	所属集合ID	必需，明确文档存放位置
parentDocumentId	string	父文档ID	可选，创建子文档时使用，构建文档层级
templateId	string	模板ID	基于模板创建时使用，快速生成标准化文档
createdAt	string	创建时间	可选，默认为当前时间，导入历史文档时使用
fullWidth	boolean	是否全屏显示	默认false，长文档建议设为true提升阅读体验
template	boolean	是否为模板文档	标记文档为模板，便于其他用户复用

响应示例

{
  "data": {
    "id": "uuid",                  // 新创建文档的ID
    "title": "文档标题",            // 文档标题
    "text": "文档内容",            // 文档内容
    "createdAt": "2025-01-01T00:00:00Z",  // 创建时间
    "updatedAt": "2025-01-01T00:00:00Z",  // 更新时间
    "publishedAt": "2025-01-01T00:00:00Z", // 发布时间
    "collectionId": "uuid",        // 所属集合ID
    "parentDocumentId": "uuid",    // 父文档ID
    "createdBy": {                 // 创建者信息
      "id": "uuid",
      "name": "用户名"
    },
    "icon": "file-text",           // 文档图标
    "color": "#000000",            // 图标颜色
    "isTemplate": false,           // 是否为模板文档
    "isArchived": false,           // 是否已归档
    "isDeleted": false             // 是否已删除
  },
  "policies": {                    // 权限信息
    "canRead": true,
    "canUpdate": true,
    "canDelete": true
  }
}

文档状态管理

归档文档 ✅ 稳定

接口用途：将文档标记为归档状态，不删除但从常规视图中隐藏。

业务应用场景：项目结束后的文档归档、暂时不需要但可能将来有用的文档处理。

基础用法

Python示例：

def archive_document(token, document_id):
    url = "/api/documents.archive"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    
    payload = {
        "id": document_id
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    return response.json()

参数解析

展开查看参数详情

参数名	类型	描述	使用建议
id	string	文档ID	必需，指定要归档的文档

响应示例

{
  "data": {
    "id": "uuid",                  // 被归档文档的ID
    "archivedAt": "2025-01-01T00:00:00Z"  // 归档时间
  }
}

⚠️ 注意：归档文档不会出现在常规文档列表中，需要通过指定statusFilter为["archived"]才能查询到。

恢复文档 ✅ 稳定

接口用途：将已归档或已删除的文档恢复到正常状态。

业务应用场景：误归档/删除文档的恢复、需要重新使用的历史文档。

基础用法

Python示例：

def restore_document(token, document_id, collection_id=None, revision_id=None):
    url = "/api/documents.restore"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    
    payload = {
        "id": document_id
    }
    
    if collection_id:
        payload["collectionId"] = collection_id
    if revision_id:
        payload["revisionId"] = revision_id
        
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    return response.json()

参数解析

展开查看参数详情

参数名	类型	描述	使用建议
id	string	文档ID	必需，指定要恢复的文档
collectionId	string	恢复到的集合ID	可选，如不指定则恢复到原集合
revisionId	string	恢复到的版本ID	可选，指定则恢复到特定历史版本

响应示例

{
  "data": {
    "id": "uuid",                  // 被恢复文档的ID
    "deletedAt": null,             // 删除时间（恢复后为null）
    "archivedAt": null             // 归档时间（恢复后为null）
  }
}

高级操作

文档搜索

搜索文档内容 ✅ 稳定

接口用途：全文搜索文档内容，支持多条件筛选和结果高亮。

业务应用场景：知识库检索功能、内容发现、相关文档推荐。

基础用法

Python示例：

def search_documents(token, query, collection_id=None):
    url = "/api/documents.search"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    
    payload = {
        "query": query,
        "statusFilter": ["published"]
    }
    
    if collection_id:
        payload["collectionId"] = collection_id
        
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    return response.json()

参数解析

展开查看参数详情

参数名	类型	描述	使用建议
query	string	搜索关键词	必需，支持空格分隔的多个关键词，使用双引号表示精确匹配
collectionId	string	集合ID	可选，限制搜索范围，提升搜索效率
documentId	string	文档ID	可选，搜索特定文档内的内容
userId	string	创建者ID	可选，搜索特定用户创建的文档
dateFilter	string	日期筛选	可选值：day, week, month, year，缩小时间范围
statusFilter	array	状态筛选	可选值：published, draft, archived
shareId	string	共享链接ID	用于通过共享链接搜索
snippetMinWords	number	摘要最小单词数	默认20，控制搜索结果摘要长度
snippetMaxWords	number	摘要最大单词数	默认30，建议不超过50以保持可读性

响应示例：与获取文档列表类似，但data字段包含匹配的内容摘要。

文档权限管理

添加用户权限 ✅ 稳定

接口用途：为特定用户授予文档访问权限，实现文档协作共享。

业务应用场景：团队协作、跨部门文档共享、临时项目成员授权。

基础用法

Python示例：

def add_document_permission(token, document_id, user_id, permission="read_write"):
    url = "/api/documents.add_user"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    
    payload = {
        "id": document_id,
        "userId": user_id,
        "permission": permission
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    return response.json()

参数解析

展开查看参数详情

参数名	类型	描述	使用建议
id	string	文档ID	必需，指定要授权的文档
userId	string	用户ID	必需，指定被授权用户
permission	string	权限级别	可选值：read（只读）, read_write（读写）, admin（管理员），根据协作需求选择适当权限

响应示例

{
  "data": {
    "documentId": "uuid",          // 文档ID
    "userId": "uuid",              // 用户ID
    "permission": "read_write"     // 授予的权限级别
  }
}

最佳实践

常见场景解决方案

1. 批量文档迁移

场景描述：需要将外部系统的多篇文档导入到Outline中，并保持原有层级结构。

解决方案：

首先创建目标集合：

# 伪代码示例
def create_collection(token, name, description):
    # 调用集合创建API

按层级顺序导入文档：

# 伪代码示例
def import_documents(token, collection_id, documents):
    # 先导入父文档，获取ID后再导入子文档
    for doc in documents:
        if not doc.get('parent_id'):  # 先处理顶级文档
            result = create_document(token, doc['title'], collection_id, doc['content'])
            doc['outline_id'] = result['data']['id']
    
    # 再处理子文档
    for doc in documents:
        if doc.get('parent_id'):
            parent_outline_id = find_outline_id(documents, doc['parent_id'])
            create_document(token, doc['title'], collection_id, doc['content'], parent_outline_id)

迁移完成后验证文档结构和内容。

2. 文档变更通知

场景描述：当重要文档更新时，需要通知相关团队成员。

解决方案：

创建Webhook监听文档更新事件：

# 伪代码示例
def create_webhook(token, url, events=["document.updated"]):
    # 调用Webhook创建API

在Webhook处理程序中实现通知逻辑：

# 伪代码示例
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event = request.json
    if event['type'] == 'document.updated':
        document_id = event['data']['id']
        # 获取文档详情
        document = get_document_details(token, document_id)
        # 获取文档权限用户
        users = get_document_permissions(token, document_id)
        # 发送通知
        for user in users:
            send_notification(user['email'], f"文档更新: {document['title']}")
    return "OK"

接口调用性能优化

批量操作优先：对于大量文档操作，尽量使用批量接口减少请求次数。
合理设置分页参数：根据实际需求调整limit参数，避免一次请求过多数据。
字段过滤：如果只需要特定字段，考虑在未来API版本中支持字段过滤（目前API返回完整对象）。
缓存策略：对不频繁变化的数据（如文档列表、用户信息）实施本地缓存。
异步处理：对于耗时操作（如文档导入、导出），使用异步处理并轮询状态。

错误排查流程

graph TD
    A[API调用失败] --> B{检查状态码}
    B -->|401| C[检查JWT令牌是否过期或无效]
    B -->|403| D[检查用户是否有操作权限]
    B -->|404| E[检查资源ID是否正确]
    B -->|422| F[检查请求参数格式和内容]
    B -->|429| G[检查是否超过API调用频率限制]
    B -->|500| H[服务器内部错误，联系管理员]
    C --> I[重新获取令牌]
    D --> J[请求相应权限或联系文档所有者]
    E --> K[验证资源ID或确认资源存在]
    F --> L[检查参数是否符合API要求]
    G --> M[降低调用频率或实现退避策略]
    I --> N[重试API调用]
    J --> N
    K --> N
    L --> N
    M --> N
    N --> O[操作成功]

第三方集成示例

Slack集成：文档更新通知

import requests
import json
from flask import Flask, request

app = Flask(__name__)

SLACK_WEBHOOK_URL = "https://hooks.slack.com/services/YOUR_SLACK_WEBHOOK"

@app.route('/outline-webhook', methods=['POST'])
def outline_webhook():
    event = request.json
    
    # 只处理文档更新事件
    if event.get('event') == 'document.updated':
        document = event.get('data', {})
        
        # 构建Slack消息
        message = {
            "text": f"📄 *文档更新通知*",
            "attachments": [
                {
                    "title": document.get('title'),
                    "title_link": f"https://your-outline-instance.com/doc/{document.get('id')}",
                    "fields": [
                        {
                            "title": "更新者",
                            "value": document.get('updatedBy', {}).get('name', '未知用户'),
                            "short": True
                        },
                        {
                            "title": "更新时间",
                            "value": document.get('updatedAt', ''),
                            "short": True
                        }
                    ],
                    "color": "#439FE0"
                }
            ]
        }
        
        # 发送到Slack
        requests.post(SLACK_WEBHOOK_URL, data=json.dumps(message),
                      headers={'Content-Type': 'application/json'})
    
    return "OK", 200

if __name__ == '__main__':
    app.run(port=3000)