M-Doc OpenAPI 接口文档

M-Doc OpenAPI 提供一组 RESTful 接口，用于程序化访问和管理组织文档和文章内容。所有接口均以 /openapi 为路径前缀。

认证

所有 OpenAPI 接口均需通过 Authorization 请求头进行认证，支持以下两种方式：

PAT（个人访问令牌）

Authorization: Bearer mdoc_pat_<token>

PAT 在创建时绑定了权限范围（Scope），调用接口时会校验是否具备所需 Scope。拥有 admin:all Scope 可访问所有接口。

API Key（AWS Signature V4）

Authorization: AWS4-HMAC-SHA256 Credential=<access_key>/<date>/<region>/<service>/aws4_request, SignedHeaders=<headers>, Signature=<signature>

需同时携带 X-Amz-Date 和 x-amz-content-sha256 请求头。API Key 认证不受 Scope 限制，具备所有 OpenAPI 接口的访问权限。

签名算法详见 API Key 签名说明。

可用 Scope

统一响应格式

JSON 接口

{
  "code": 200,
  "message": "成功",
  "data": { }
}

纯文本接口

Manifest 和 Markdown Content 接口直接返回 text/markdown; charset=utf-8 纯文本，不使用 JSON 包装。

错误响应

{
  "code": 401,
  "message": "错误描述"
}

接口列表

1. 获取组织文档列表

获取指定组织下的文档列表，支持分页。

GET /openapi/organizations/:orgSlug/documents

所需权限：read:documents

路径参数

查询参数

响应

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "id": 1,
      "name": "产品手册",
      "slug": "product-manual",
      "description": "产品使用文档",
      "organization_name": "示例组织",
      "organization_slug": "example-org",
      "default_version_id": 10,
      "visibility": "public",
      "user_role": "admin",
      "updated_at": "2026-03-04T10:00:00Z"
    }
  ]
}

data 字段说明

示例请求

curl -X GET "https://your-domain.com/openapi/organizations/example-org/documents?page=1&page_size=10" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

2. 获取文档详情

根据组织 slug 和文档 slug 获取文档详细信息。

GET /openapi/organizations/:orgSlug/documents/:docSlug

所需权限：read:documents

路径参数

响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 1,
    "organization_id": 5,
    "organization_name": "示例组织",
    "organization_slug": "example-org",
    "name": "产品手册",
    "slug": "product-manual",
    "description": "产品使用文档",
    "visibility": "public",
    "default_version_id": 10,
    "status": "published",
    "created_by": 1,
    "user_role": "admin",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-03-04T10:00:00Z"
  }
}

data 字段说明

示例请求

curl -X GET "https://your-domain.com/openapi/organizations/example-org/documents/product-manual" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

3. 获取文章目录树

获取指定文档版本下的文章层级目录树。

GET /openapi/versions/:id/articles

所需权限：read:articles

路径参数

响应

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "id": 1,
      "title": "快速入门",
      "article_id": 100,
      "article_version_id": 200,
      "parent_article_id": 0,
      "sort_order": 1,
      "children": [
        {
          "id": 2,
          "title": "安装指南",
          "article_id": 101,
          "article_version_id": 201,
          "parent_article_id": 100,
          "sort_order": 1,
          "children": []
        }
      ]
    }
  ]
}

data 字段说明（ArticleTreeNode）

示例请求

curl -X GET "https://your-domain.com/openapi/versions/10/articles" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

4. 获取文章详情

获取指定文档版本下某篇文章的详细内容，包含 Markdown 原文和渲染后的 HTML。

GET /openapi/versions/:id/articles/:articleId

所需权限：read:articles

路径参数

响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "article": {
      "id": 100,
      "document_id": 1,
      "stable_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "快速入门",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-03-04T10:00:00Z"
    },
    "current_version": {
      "id": 200,
      "article_id": 100,
      "commit_hash": "abc1234567890def1234567890abcdef12345678",
      "short_hash": "abc1234",
      "commit_message": "更新快速入门文档",
      "parent_commit_hash": "def7890123456abc7890123456def78901234567",
      "content": "# 快速入门\n\n这是文章的 Markdown 内容...",
      "status": "published",
      "created_by": 1,
      "created_at": "2026-03-04T10:00:00Z"
    },
    "content_html": "<h1>快速入门</h1><p>这是文章的 Markdown 内容...</p>",
    "parent_article_id": null,
    "sort_order": 1
  }
}

data 字段说明（ArticleDetailResponse）

示例请求

curl -X GET "https://your-domain.com/openapi/versions/10/articles/100" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

5. 获取文档清单（Manifest）

获取文档的结构化清单，以 Markdown 格式返回，包含文档目录结构和各文章的访问链接。适用于 AI 阅读和文档索引场景。

GET /openapi/organizations/:orgSlug/documents/:docSlug/manifest

所需权限：read:articles

路径参数

查询参数

响应

• Content-Type: text/markdown; charset=utf-8
• 成功（200）：返回 Markdown 格式的文档清单
• 失败（404）：返回 text/plain 错误信息，格式为 Error: 错误描述

示例请求

curl -X GET "https://your-domain.com/openapi/organizations/example-org/documents/product-manual/manifest" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

# 指定版本
curl -X GET "https://your-domain.com/openapi/organizations/example-org/documents/product-manual/manifest?version=v2.0.0" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

6. 获取文章 Markdown 原文

获取指定文章的原始 Markdown 内容，以纯文本形式返回。适用于 AI 阅读和内容处理场景。

GET /openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md

所需权限：read:articles

路径参数

查询参数

响应

• Content-Type: text/markdown; charset=utf-8
• 成功（200）：返回文章的 Markdown 原文
• 失败（400/404）：返回 text/plain 错误信息，格式为 Error: 错误描述

示例请求

curl -X GET "https://your-domain.com/openapi/organizations/example-org/documents/product-manual/articles/100/content.md" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

指定版本

curl -X GET "https://your-domain.com/openapi/organizations/example-org/documents/product-manual/articles/100/content.md?version=v2.0.0" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

7. 文章语义搜索

在指定文档中对文章内容进行语义搜索，返回按相关度排序的匹配结果。

GET /openapi/organizations/:orgSlug/documents/:docSlug/search

所需权限：read:articles

路径参数

查询参数

响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "results": [
      {
        "article_id": 100,
        "title": "快速入门",
        "score": 0.92,
        "content": "文章内容摘要...",
        "markdown_url": "https://your-domain.com/openapi/organizations/example-org/documents/product-manual/articles/100/content.md",
        "browser_url": "https://your-domain.com/example-org/product-manual/articles/100"
      }
    ],
    "total": 1
  }
}

data 字段说明（SearchArticleResponse）

示例请求

curl -X GET "https://your-domain.com/openapi/organizations/example-org/documents/product-manual/search?q=如何安装&top_k=5&min_score=0.6" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

8. 创建文章

在指定文档版本下创建一篇新文章。文章创建后处于草稿状态，需调用发布接口生成正式版本。

POST /openapi/versions/:id/articles

所需权限：write:articles

路径参数

请求体

{
  "title": "新文章标题",
  "content": "文章的 Markdown 内容",
  "parent_article_id": 100,
  "sort_order": 1
}

响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 101,
    "document_id": 1,
    "stable_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "title": "新文章标题",
    "created_at": "2026-04-10T10:00:00Z",
    "updated_at": "2026-04-10T10:00:00Z"
  }
}

data 字段说明（ArticleResponse）

示例请求

curl -X POST "https://your-domain.com/openapi/versions/10/articles" \
  -H "Authorization: Bearer mdoc_pat_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新文章标题",
    "content": "# 新文章\n\n这是文章内容。",
    "sort_order": 1
  }'

9. 更新文章

更新指定文档版本下的文章内容或属性。所有字段均为可选，仅更新传入的字段。

PUT /openapi/versions/:id/articles/:articleId

所需权限：write:articles

路径参数

请求体

{
  "title": "更新后的标题",
  "content": "更新后的 Markdown 内容",
  "parent_article_id": 100,
  "sort_order": 2
}

响应

{
  "code": 200,
  "message": "成功",
  "data": null
}

示例请求

curl -X PUT "https://your-domain.com/openapi/versions/10/articles/100" \
  -H "Authorization: Bearer mdoc_pat_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "更新后的标题",
    "content": "# 更新后的内容\n\n这是更新后的文章。"
  }'

10. 删除文章

从指定文档版本中删除一篇文章。

DELETE /openapi/versions/:id/articles/:articleId

所需权限：write:articles

路径参数

响应

{
  "code": 200,
  "message": "成功",
  "data": null
}

错误响应

示例请求

curl -X DELETE "https://your-domain.com/openapi/versions/10/articles/100" \
  -H "Authorization: Bearer mdoc_pat_xxxxx"

11. 发布文章

将文章的当前草稿内容发布为正式版本，生成一个新的文章版本快照（类似 Git commit）。

POST /openapi/versions/:id/articles/:articleId/publish

所需权限：write:articles

路径参数

请求体

{
  "commit_message": "更新了安装说明和配置示例"
}

响应

{
  "code": 200,
  "message": "成功",
  "data": null
}

示例请求

curl -X POST "https://your-domain.com/openapi/versions/10/articles/100/publish" \
  -H "Authorization: Bearer mdoc_pat_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "commit_message": "更新了安装说明和配置示例"
  }'