Mikipage API

Mikipage REST API 是产品的完整功能集。你在 Mikipage 上能做的一切——创建和搜索笔记、构建 AI 页面、管理群组、发布到 Web、运行 AI——都可以通过这里实现。

使用 Mikipage 的其他方式都是此 API 的有意子集：

Web 是面向日常使用的、主张明确且极简的界面。它会替你做出选择，并隐藏高级选项。
MCP 是面向 AI 高级用户的精选子集。为确保 AI 使用安全且成本可控，其中有些操作会被有意省略（删除笔记和页面、账户设置、群组和成员管理、文件字节、评论）。尤其是删除操作仍不会加入 MCP，因为它不可逆，而且 AI 代理很容易批量执行——请改用 Web 或此 API 进行删除。参见 [1]。

Web 或 MCP 上存在的任何内容都可以通过 API 表达，但有三个有意的例外：匿名公共内容（落地页、/docs、已发布页面）、聊天产品本身，以及凭据、套餐变更和购买。这些按设计仅限 Web，且此列表是封闭的。其他一切都位于这里，不带主观限制，并提供完整选项集。

API 和 MCP 永远不会向非公共群组成员的人提供该群组的内容——公共内容应在网站上阅读。对于这类请求，API 的回答与私有群组完全相同——包括评论：若要评论自己不是成员的公共页面，请使用网站上的该页面。

Python SDK

我们在开源 miki_client 库中提供官方 Python SDK。它会为你处理身份验证（包括 OAuth 浏览器流程、令牌缓存和自动刷新）、分页、文件上传以及预签名下载流程。

miki_client 目前位于私有 GitHub 仓库中，稍后会公开发布（PyPI + 开源）。下面的示例同时展示 SDK 和原始 HTTP 调用，因此你今天就可以用任何语言进行集成。

from miki_client import MikiClient

# OAuth（默认）：打开浏览器登录，然后缓存并自动刷新令牌。
client = MikiClient()

note = client.create_note("# Shopping list\n- milk\n- eggs")
print(note["id"])

基础 URL 和约定

基础 URL：https://api.mikipage.com——没有版本前缀，也没有路径前缀。GET https://api.mikipage.com/notes 会列出你的笔记。
两个主机名。 API 位于 api.mikipage.com。登录则不在这里：OAuth 端点、/.well-known/ 发现文档以及 OpenAPI 文档全部位于 https://mikipage.com。你需要同时使用两者，且不能从一个推导出另一个——不要假设它们共享域名。
处处使用 JSON：请求和响应正文均为 JSON，字段名使用 snake_case。
部分更新使用 PATCH——只发送你想更改的字段。
列表响应使用封装结构：
```
{
  "items": [ /* ... */ ],
  "next_cursor": "opaque-string-or-null",
  "has_more": false
}
```
要进行分页，请将 next_cursor 作为 cursor 查询参数传回，直到 has_more 为 false。
时间戳是 RFC 3339 字符串（例如 2026-07-23T18:04:00Z）。
错误使用 RFC 9457 application/problem+json。每个错误正文都包含稳定的、机器可读的 code，你可以据此进行判断——永远不要对人类可读的 detail 进行字符串匹配：
```
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "detail": "Note not found",
  "request_id": "req_..."
}
```
常见代码：invalid_request（400）、unauthenticated / invalid_token（401）、insufficient_credits（402）、permission_denied / insufficient_scope / quota_exceeded（403）、not_found（404）、conflict（409）、content_too_large（413）、rate_limited（429）、internal（500）、unavailable（503）。缺失的资源与无权查看的资源会返回完全相同的 not_found 正文——不会泄露资源是否存在。
OpenAPI：机器可读的规范通过 GET https://mikipage.com/openapi.json（OpenAPI 3.1）提供，并呈现为交互式 API 参考。它是线路契约的事实标准：TypeScript 服务器和 Python SDK 所依据的请求与响应类型都从中生成，因此其中记录的结构就是代码实际生成的结构。SDK 的方法本身则是手写的。

身份验证

Mikipage 使用 OAuth 2.1 访问令牌（Cognito 签发的 JWT），并在边缘进行验证。每个请求都要通过 Bearer 标头发送令牌：

Authorization: Bearer <access-token>

如何获取令牌

OAuth 授权码 + PKCE（推荐用于应用和交互式工具）。通过 GET /.well-known/oauth-authorization-server 发现端点：
- authorization_endpoint：https://mikipage.com/oauth/authorize
- token_endpoint：https://mikipage.com/oauth/token
- registration_endpoint：https://mikipage.com/oauth/register（动态客户端注册）
长期运行的 CLI/SDK 会话会签发刷新令牌。Python SDK 会自动完成整个流程——浏览器登录、令牌缓存（~/.mikipage/）和静默刷新。

凭据生命周期归 Cognito 管理，而非 API 管理——没有登录端点，也不会将任何 Mikipage 密码交给客户端。
无头模式 / CI（机器上无法使用浏览器时）：使用相同的 OAuth 流程，URL 会打印出来供你在任意位置打开，然后将重定向结果粘贴回来：
```
uv run scripts/auth.py --no-browser
```
由此产生的会话是普通的可续期 OAuth 会话，因此这是一次性步骤。

作用域

未强制执行。 有效令牌会授予你可访问的一切内容的完整访问权限。作用域仅是建议性文档——它们描述 API 设计所依据的授权模型，目前没有计划实施按作用域强制执行（GitHub #256）。不要构建任何依赖令牌受限的功能。

每个操作都带有 x-required-scopes 注释，该注释发布在 openapi.json 中，并显示在API 参考的每个操作旁。它记录操作所属的能力——大致按每种资源划分为一个族：notes:*、pages:*、groups:*、runs:*、account:*、usage:read 和 publishing。

评论没有自己的作用域——它们使用父笔记或页面的 :read / :write。每个端点都需要令牌；不存在匿名命名空间。

快速开始

创建笔记

笔记就是 Markdown 内容。Mikipage 会自动为其建立 AI 搜索和页面匹配索引。

SDK

note = client.create_note(
    "# Meeting notes\n\nDiscussed Q3 roadmap. #planning",
    group_ids=["<group-id>"],   # 可选：创建时分享到群组
)
note_id = note["id"]

HTTP

curl -X POST https://api.mikipage.com/notes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Meeting notes\n\nDiscussed Q3 roadmap. #planning"}'

响应（Note）：

{
  "id": "note_abc123",
  "content": "# Meeting notes\n\nDiscussed Q3 roadmap. #planning",
  "starred": false,
  "archived": false,
  "stale_match": false,
  "owner_id": "…",
  "state": "active",
  "created_at": "2026-07-23T18:04:00Z",
  "updated_at": "2026-07-23T18:04:00Z"
}

获取笔记

SDK

note = client.get_note("note_abc123")

# 在一次调用中获取相关数据：
note = client.get_note("note_abc123", expand=["groups", "pages", "attachments"])

HTTP

curl https://api.mikipage.com/notes/note_abc123?expand=groups,pages \
  -H "Authorization: Bearer $TOKEN"

如果你拥有某条笔记，或该笔记已分享到你所属的群组，则可以读取它。

受保护的笔记（"is_protected": true）会将其秘密文本以加密的 Base64 信封形式放在 protected 中；content 是其明文描述。服务器无法解密——持有密码的客户端可以解密。[2] 描述了该格式，OpenAPI 参考则记录了 PATCH /notes/{id} 如何保护笔记。

搜索笔记

POST /notes/search 会根据跨语言语义相似度对笔记进行排序。q 中任何被引号包围的子字符串都会成为严格的短语过滤条件。这是读取操作，只需要 notes:read 作用域，并使用请求正文，因此查询文本不会出现在 URL 和服务器日志中。

results = client.search_notes(q='roadmap "Q3"', tags=["planning"], limit=20)
for item in results["items"]:
    print(item["id"], item["content"][:60])

GET /notes 是普通列表接口，按最近时间排序。它是独立端点，不接受搜索参数。

API 参考

每个端点及其参数、请求正文和响应结构都位于交互式 API 参考中——直接从 OpenAPI 文档渲染，因此始终与 API 实际提供的内容保持同步。

如果你想生成客户端或将其载入自己的工具，也可以通过 GET https://mikipage.com/openapi.json 获取原始文档。

其中的操作按笔记、附件、页面、评论、群组、发布、AI 运行和账户进行分组——也就是上述介绍的相同族群。

待实现

以下功能已经完成设计，但尚不可用。它们需要额外的后端工作，并已安排在后续迭代中——目前请基于现有界面进行开发。

聊天不在此列表中，也不会加入：它是 Web 应用功能，没有公开 API，这是有意为之。其结构与为之构建的 UI 紧密相关，将其冻结为公共契约对任何人都没有好处。

Webhook 和事件：完整的 webhook 系列，以及服务器发送事件流（GET /events）。
运行：可通过运行 ID 读取（GET /runs/{id}）、带游标的全局跨实体运行列表、POST /runs/{id}/cancel，以及创建时返回运行 ID 的服务器运行。
恢复：用于软删除项目的 POST /notes/{id}/restore 和 POST /pages/{id}/restore。
图片：PUT /me/picture 和 PUT /groups/{id}/picture（目前客户端直接上传到存储）。
可靠性：Idempotency-Key 支持和速率限制。
个人访问令牌（PAT）：设计已为 PAT 做好准备（预留 mikip_ 前缀）；OAuth + 刷新令牌覆盖当前流程，包括通过 --no-browser 运行的无头流程。设备授权授予流程正在评估中，以便让该场景更顺畅地完成初始化。
列表改进：列表端点增加 stale= 过滤器和 expand=。