Outline API 完全指南：从基础集成到高级应用

2026-03-12 03:06:13作者：柏廷章Berta

核心能力概览

Outline 提供了一套完整的 RESTful API，使开发者能够与团队知识库进行深度集成。通过这些接口，你可以实现文档的全生命周期管理、高级搜索与权限控制，以及构建自定义集成方案。本指南将帮助你快速掌握 API 的使用方法，从基础操作到高级应用场景。

文档生命周期管理

功能概览

接口名称	功能描述	权限要求
documents.create	创建新文档	认证用户
documents.info	获取文档详情	认证用户或共享链接访问者
documents.update	更新文档内容	文档管理员或创建者
documents.delete	删除文档	文档管理员或创建者
documents.archive	归档文档	文档管理员或创建者
documents.restore	恢复文档	文档管理员或创建者
documents.move	移动文档	文档管理员或创建者
documents.duplicate	复制文档	文档查看权限

创建文档

功能场景：在指定集合中创建新文档，支持基于模板创建或自定义内容。

核心参数：

title: 文档标题（必填）
text: 文档内容，使用 ProseMirror JSON 格式（必填）
collectionId: 所属集合 ID（必填）
publish: 是否立即发布（默认：false）

[!NOTE] ProseMirror JSON 格式是一种结构化的文档表示方式，包含节点类型、属性和内容等信息，适合富文本编辑场景。

请求示例：

fetch('/api/documents.create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    title: "API 集成指南",
    text: {
      type: "doc",
      content: [
        {
          type: "paragraph",
          content: [
            { type: "text", text: "这是使用 Outline API 创建的文档" }
          ]
        }
      ]
    },
    collectionId: "your-collection-id",
    publish: true
  })
})
.then(response => response.json())
.then(data => console.log("创建成功:", data.data.id));

响应示例：

{
  "data": {
    "id": "doc-uuid",
    "title": "API 集成指南",
    "createdAt": "2025-01-01T00:00:00Z",
    "collectionId": "your-collection-id",
    "createdBy": {
      "id": "user-uuid",
      "name": "用户名"
    },
    "isTemplate": false,
    "isPublished": true
  },
  "policies": {
    "canRead": true,
    "canUpdate": true,
    "canDelete": true
  }
}

更新文档

功能场景：修改现有文档的内容、标题或属性，支持部分更新。

核心参数：

id: 文档 ID（必填）
title: 新标题（可选）
text: 新内容（可选）
append: 是否追加内容而非替换（默认：false）

请求示例：

fetch('/api/documents.update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    id: "doc-uuid",
    title: "API 集成完全指南",
    append: true,
    text: {
      type: "doc",
      content: [
        {
          type: "paragraph",
          content: [
            { type: "text", text: "这是追加的内容" }
          ]
        }
      ]
    }
  })
})
.then(response => response.json())
.then(data => console.log("更新成功:", data.data.id));

文档操作流程

graph TD
    A[创建文档] --> B{需要更新?};
    B -- 是 --> C[更新文档内容];
    B -- 否 --> D[发布文档];
    C --> D;
    D --> E{需要调整位置?};
    E -- 是 --> F[移动文档];
    E -- 否 --> G[完成];
    F --> G;
    G --> H{需要复制?};
    H -- 是 --> I[复制文档];
    H -- 否 --> J{需要归档?};
    J -- 是 --> K[归档文档];
    J -- 否 --> L[完成];
    K --> M{需要恢复?};
    M -- 是 --> N[恢复文档];
    M -- 否 --> O[删除文档];

删除文档

功能场景：将文档移至回收站或永久删除。

核心参数：

id: 文档 ID（必填）
permanent: 是否永久删除（默认：false）

[!WARNING] 永久删除操作不可恢复，请谨慎使用。建议先使用普通删除（放入回收站）进行确认。

请求示例：

fetch('/api/documents.delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    id: "doc-uuid",
    permanent: false
  })
})
.then(response => response.json())
.then(data => console.log("删除成功:", data.data.id));

高级功能

功能概览

接口名称	功能描述	权限要求
documents.search	搜索文档内容	认证用户或共享链接访问者
documents.search_titles	搜索文档标题	认证用户
documents.add_user	添加用户权限	文档管理员
documents.remove_user	移除用户权限	文档管理员
documents.add_group	添加组权限	文档管理员
documents.remove_group	移除组权限	文档管理员
documents.export	导出文档	文档查看权限
documents.import	导入文档	认证用户

文档搜索

功能场景：根据关键词搜索文档内容或标题，支持过滤和排序。

核心参数：

query: 搜索关键词（必填）
collectionId: 限定集合（可选）
statusFilter: 状态筛选（可选，如 ["published"]）

请求示例：

fetch('/api/documents.search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    query: "API 集成",
    collectionId: "your-collection-id",
    statusFilter: ["published"]
  })
})
.then(response => response.json())
.then(data => console.log("搜索结果:", data.data));

权限管理

功能场景：管理用户或组对文档的访问权限，支持细粒度权限控制。

核心参数：

id: 文档 ID（必填）
userId/groupId: 用户或组 ID（必填）
permission: 权限级别（必填，可选值：read, read_write, admin）

请求示例：

// 添加用户权限
fetch('/api/documents.add_user', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    id: "doc-uuid",
    userId: "user-uuid",
    permission: "read_write"
  })
})
.then(response => response.json())
.then(data => console.log("权限添加成功"));

[!TIP] 权限级别说明：

read: 只读权限，可查看但不能修改

read_write: 读写权限，可查看和修改但不能管理权限

admin: 管理员权限，拥有完全控制权

导入导出

功能场景：导出文档为 HTML/Markdown 格式，或从文件导入新文档。

导出请求示例：

fetch('/api/documents.export', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Accept': 'text/markdown'
  },
  body: JSON.stringify({
    id: "doc-uuid"
  })
})
.then(response => response.text())
.then(markdown => {
  // 保存为本地文件
  const blob = new Blob([markdown], { type: 'text/markdown' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'document.md';
  a.click();
});

导入请求示例：

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('collectionId', 'your-collection-id');
formData.append('publish', 'true');

fetch('/api/documents.import', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: formData
})
.then(response => response.json())
.then(data => console.log("导入任务ID:", data.data.taskId));

系统集成

功能概览

接口名称	功能描述	权限要求
-	错误处理	所有接口
-	调用流程	所有接口
-	频率限制	所有接口

认证机制

Outline API 使用 JWT（JSON Web Token） 进行认证。JWT 是一种基于 JSON 的轻量级认证令牌，可在客户端和服务器之间安全地传输信息。

认证流程：

用户登录系统获取 JWT 令牌
在 API 请求头中添加 Authorization: Bearer YOUR_JWT_TOKEN
服务器验证令牌有效性并授权访问

[!NOTE] JWT 令牌通常有过期时间，需要定期刷新。具体实现请参考 Outline 认证文档。

错误处理

API 错误响应遵循统一格式，包含错误名称、消息和详细信息：

[!ERROR] 400 Bad Request

描述：请求参数错误

解决：检查请求参数格式和值是否符合要求

[!ERROR] 401 Unauthorized

描述：未授权访问

解决：检查 JWT 令牌是否有效或已过期，重新获取令牌

[!ERROR] 403 Forbidden

描述：权限不足

解决：确认当前用户是否有操作该资源的权限

[!ERROR] 404 Not Found

描述：资源不存在

解决：检查资源 ID 是否正确或资源是否已被删除

[!ERROR] 429 Too Many Requests

描述：请求频率超限

解决：减少请求频率或实现请求限流机制

错误处理代码示例：

async function apiRequest(url, data) {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_JWT_TOKEN'
      },
      body: JSON.stringify(data)
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`${error.error.name}: ${error.error.message}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('API 请求失败:', error.message);
    // 处理错误，如重试、提示用户等
    throw error;
  }
}

接口调用频率限制

为保护系统稳定性，Outline API 实施以下调用频率限制：

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

当超过限制时，接口将返回 429 状态码。建议实现请求限流机制，避免触发限制。

限流处理建议：

实现指数退避重试机制
对批量操作进行分组处理
使用缓存减少重复请求
监控请求频率并动态调整

接口关系图

graph TD
    A[认证] --> B[文档管理];
    A --> C[高级功能];
    B --> D[创建文档];
    B --> E[更新文档];
    B --> F[删除文档];
    B --> G[移动文档];
    B --> H[复制文档];
    C --> I[搜索文档];
    C --> J[权限管理];
    C --> K[导入导出];
    D --> L[发布文档];
    E --> L;
    L --> M[归档文档];
    M --> N[恢复文档];
    I --> O[搜索标题];
    I --> P[搜索内容];
    J --> Q[添加用户权限];
    J --> R[添加组权限];
    K --> S[导出文档];
    K --> T[导入文档];

接口选择决策树

graph TD
    A[需要操作文档?] -->|是| B[操作类型?];
    A -->|否| Z[结束];
    B -->|创建| C[documents.create];
    B -->|查看| D[documents.info];
    B -->|修改| E[documents.update];
    B -->|删除| F[documents.delete];
    B -->|移动| G[documents.move];
    B -->|复制| H[documents.duplicate];
    B -->|归档| I[documents.archive];
    B -->|恢复| J[documents.restore];
    B -->|搜索| K[搜索类型?];
    K -->|标题| L[documents.search_titles];
    K -->|内容| M[documents.search];
    B -->|权限| N[权限类型?];
    N -->|用户| O[documents.add_user/remove_user];
    N -->|组| P[documents.add_group/remove_group];
    B -->|导入导出| Q[操作类型?];
    Q -->|导入| R[documents.import];
    Q -->|导出| S[documents.export];

常见集成场景

批量导入工具

场景描述：从现有系统迁移文档到 Outline，或定期导入外部内容。

实现步骤：

前置条件：获取管理员权限的 JWT 令牌，准备好待导入的文档文件
操作步骤：
- 遍历待导入文件列表
- 对每个文件调用 documents.import 接口
- 跟踪导入任务状态
- 处理导入结果和错误
预期结果：所有文档成功导入到指定集合，保留原始格式和结构

代码示例：

async function batchImport(files, collectionId) {
  const results = [];
  
  for (const file of files) {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('collectionId', collectionId);
    formData.append('publish', 'true');
    
    try {
      const response = await fetch('/api/documents.import', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_JWT_TOKEN'
        },
        body: formData
      });
      
      const data = await response.json();
      results.push({ file: file.name, taskId: data.data.taskId, status: 'success' });
    } catch (error) {
      results.push({ file: file.name, error: error.message, status: 'failed' });
    }
  }
  
  return results;
}

权限同步服务

场景描述：将外部系统的用户和权限信息同步到 Outline，保持权限一致性。

实现步骤：

前置条件：获取管理员权限的 JWT 令牌，获取外部系统权限数据
操作步骤：
- 获取 Outline 现有文档列表
- 对比外部系统权限数据
- 对差异部分调用权限管理接口进行调整
- 记录同步日志
预期结果：Outline 文档权限与外部系统保持一致

接口性能优化建议

分页参数设置

对于返回列表的接口（如 documents.list、documents.search），合理设置分页参数可以显著提升性能：

limit: 建议设置为 20-50，根据数据大小调整
offset: 实现分页加载，避免一次性加载过多数据
实现无限滚动或分页控件，按需加载数据

示例：

// 分页获取文档列表
async function getDocuments(collectionId, page = 1, pageSize = 20) {
  return apiRequest('/api/documents.list', {
    collectionId,
    sort: 'updatedAt',
    direction: 'DESC',
    offset: (page - 1) * pageSize,
    limit: pageSize
  });
}

缓存策略

对不常变化的数据（如文档列表、用户信息）进行本地缓存
使用 ETag 或 Last-Modified 头实现条件请求
实现缓存失效机制，确保数据最终一致性

示例：

// 带缓存的文档详情获取
async function getDocumentWithCache(id) {
  const cacheKey = `document_${id}`;
  const cached = localStorage.getItem(cacheKey);
  
  if (cached) {
    return JSON.parse(cached);
  }
  
  const data = await apiRequest('/api/documents.info', { id });
  localStorage.setItem(cacheKey, JSON.stringify(data));
  
  // 设置10分钟缓存过期
  setTimeout(() => {
    localStorage.removeItem(cacheKey);
  }, 10 * 60 * 1000);
  
  return data;
}