文件与版本
Markdown 版写入、读取、编辑和整理文件,比较和回滚版本,处理 Agent 的提案。
写入文件
PUT /v2/spaces/{space_id}/files 创建或替换一个文件,请求体即文件内容。返回时写入已提交,可以立即读取。大小上限、状态码和请求头见参考页。
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: text/markdown" \
--data-binary "Mirabase keeps files, knowledge and memory in one place."- 查看响应的
version_created:字节和媒体类型都没有变化时为false,不产生版本,也不计配额。 - 未携带
Content-Type时,文件存为application/octet-stream。 - 要等到这个版本可以检索再返回,带上 Prefer: wait=N。该 API Key 已有 4 个等待中的请求时不再等待,响应也不带
Preference-Applied。 - 带
branch参数时写到分支而不是主线,见 分支与挂载。
记录发生时间、元数据和记忆开关
一次写入还可以记下三项:内容发生的时间 occurred_at、你自己的元数据 metadata,以及是否从中提炼记忆 memory_exclude。它们记在文件的 Entry 上,不随版本变化。PUT 的请求体是文件字节,所以这三项作为查询参数发送,metadata 是 URL 编码的 JSON。
# The body is the file, so the three values ride in the query. --url-query (curl 7.87 or newer)
# URL-encodes each one; metadata is a JSON object.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files" \
--url-query "path=/recordings/2026-11-06-standup.m4a" \
--url-query "occurred_at=2026-11-06T09:30:00+08:00" \
--url-query 'metadata={"device":"recorder-01","room":"3f"}' \
--url-query "memory_exclude=true" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: audio/mp4" \
--data-binary @standup.m4a- 只更新传入的项:覆盖写入已有文件时,未传入的项保持不变。内容未变时同样生效:再次写入相同的字节、只传入新的
occurred_at,返回version_created: false,发生时间随之更新。 - 批量写入 的每一条和 大文件 的完成请求里,它们是同名的请求体字段。
- 事后修改用
PATCH /v2/entries/{entry_id}。
避免覆盖已有修改
不带条件时后写覆盖,版本链仍然完整。要避免覆盖,把读到的 ETag 放进 If-Match;只想新建时发送 If-None-Match: *。条件请求的完整规则见 API 约定。
# Fails with 412 if someone wrote a newer version since you read this one.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H 'If-Match: "ver_2b10"' \
-H "Content-Type: text/markdown" \
--data-binary @hello.md
# Fails with 412 if the file already exists.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/new.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "If-None-Match: *" \
-H "Content-Type: text/markdown" \
--data-binary @new.md收到 412 precondition_failed 时,错误中的 current_version_id 是当前版本:重新读取、合并你的修改,再用新的 ETag 写入。
编辑文本
PATCH /v2/spaces/{space_id}/files 按字符串替换,不必发送整个文件。只支持 UTF-8 文本;每条 old_text 必须恰好出现一次,除非设置 replace_all。
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"edits": [{"old_text": "one place", "new_text": "a single place"}]}'编辑失败时不产生版本。edit_no_match 时重新读取再编辑;edit_ambiguous 时补充上下文或设置 replace_all;文件太大或不是文本时改用 PUT 替换。错误码和大小上限见参考页。
读取文件
GET /v2/spaces/{space_id}/files 按路径读取,GET /v2/entries/{entry_id}/content 按 id 读取,两者参数相同,默认读取最新版本。view 决定返回哪种形式,默认是原始字节。文本文件的 text 视图写入后即可读取,其他视图需等待处理完成。
读取旧版本带 version,按快照读取带 snapshot(见 快照),读取部分字节用 Range。各参数的规则见参考页。
下载地址
要把大文件交给浏览器或其他服务,用 GET /v2/spaces/{space_id}/files/content-url 或 GET /v2/entries/{entry_id}/content-url 为原始字节签发短期地址,获取时不需要 API Key。
# A signed URL for the original bytes, valid 60 to 300 seconds. Fetch it without the key.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/content-url?path=/videos/talk.mp4&expires_in=120" \
-H "Authorization: Bearer $MIRABASE_API_KEY"管理目录
GET /v2/spaces/{space_id}/tree 列出目录。POST /v2/spaces/{space_id}/tree/operations 按顺序执行 mkdir、move、copy、delete 和 restore,全部生效或全部不生效。
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operations": [
{"op": "mkdir", "path": "/archive/2026"},
{"op": "move", "from": "/notes/old.md", "to": "/archive/2026/old.md"},
{"op": "copy", "from": "/templates/report.md", "to": "/reports/2026-11.md"},
{"op": "delete", "path": "/drafts", "recursive": true}
]}'move和copy的to是完整的新路径。目标被占用时返回 409path_conflict,不覆盖也不合并。- 保留响应里的
delete_batch_id:它能恢复这次请求删除的全部内容。 - 每个复制出的文件是新的 Entry,列在响应的
copies里;历史不复制,之后像新文件一样处理。 - 超过同步上限的子树返回 409
subtree_too_large,请改用 以任务方式运行大型目录操作。
路径规则
路径是绝对路径,以 / 开头,结尾不带 /;名字按 NFKC 和大小写折叠比较,所以 /Docs 和 /docs 是同一个目录。长度和字符的完整规则见 DevPath。
/.mirabase/ 是保留路径,写入返回 403 reserved_path。例外是 /.mirabase/skills/<name>/...,那里存放你的技能文件,context 会读取其中的 SKILL.md。/.mirabase/memory/MEMORY.md 是生成的只读视图,见 记忆;开启了离线整理的部署上,/.mirabase/memory/RECENT.md 也是,见 索引写法。
以任务方式运行大型目录操作
超过同步上限的单条 move、copy、递归 delete 或按 delete_batch_id 的 restore,带 Prefer: respond-async 时改为任务执行,返回 202、job_id 和 Location: /v2/jobs/{job_id}。按 API 约定 跟踪任务。
# One operation over the synchronous limit runs as a job: 202 with job_id.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Prefer: respond-async" \
-H "Content-Type: application/json" \
-d '{"operations": [{"op": "delete", "path": "/old-exports", "recursive": true}]}'
# Poll until status is succeeded or failed.
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"move 是一个事务,delete、restore 和 copy 则分批执行,不是原子操作:删除任务失败时会留下删除了一部分的目录,用 result.delete_batch_id 恢复。批量写入
POST /v2/spaces/{space_id}/files/batch 在一个请求里写入和删除多个小文本文件。每个条目单独提交,单条失败不影响其余条目;每条结果有自己的 status,按位置对应请求条目。
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/batch" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: import-2026-11-06" \
-H "Content-Type: application/json" \
-d '{"items": [
{"op": "put", "path": "/notes/a.md", "content": "First note", "media_type": "text/markdown"},
{"op": "delete", "path": "/notes/old.md"}
]}'带相同的 Idempotency-Key 重新发送,可以完成中途中断的批次:已提交的条目重放,其余条目继续执行。单条 DELETE 第二次调用返回 404;重试时需要区分“已删除”和“原本不存在”,请用这个接口。
上传大文件
超过 16 MiB 的文件使用分片上传:发起上传、获取分片地址、逐片 PUT,最后完成上传。完成时才解析路径,之后的行为与 PUT 相同,包括 If-Match 和 If-None-Match: *。
# 1. Start the upload. checksum_sha256 is the Base64 SHA-256 of the whole file.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/uploads" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "/videos/talk.mp4", "size": 734003200, "media_type": "video/mp4",
"checksum_sha256": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="}'
# 2. Ask for part URLs, at most 128 at a time. Each one lasts five minutes.
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/parts" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"part_numbers": [1, 2, 3]}'
# 3. PUT each part to its URL with the returned required_headers, and keep each ETag.
# 4. Finish. The file appears at its path now.
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/complete" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"parts": [{"part_number": 1, "etag": "\"9b2c\""}, {"part_number": 2, "etag": "\"71fd\""}]}'- 上传中断后再次调用
POST /v2/uploads/{upload_id}/parts:它不再返回已收到的分片,因此可以续传。 - 分片地址和上传会话都会过期,过期后只能重新发起上传。有效期见参考页。
添加没有路径的来源
POST /v2/spaces/{space_id}/ingest 导入网址、文本或对话(见 记忆),返回 202 以及 entry_id、version_id 和 job_id。一次调用创建一个 Entry,相同内容导入两次会创建两个,因此重试时请带 Idempotency-Key。网址在响应之后抓取,无效网址表现为失败的任务。
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: article-2026-11-06" \
-H "Content-Type: application/json" \
-d '{"kind": "url", "url": "https://example.com/article"}'导入文本和对话时可以带 redact_secrets,在保存之前替换看起来像凭据的内容。它只识别形状明确的凭据,不能代替你自己的脱敏。导入对话时还可以带 memory_instructions,说明在你的应用里哪些内容需要记住。
比较和回滚版本
GET /v2/entries/{entry_id}/versions 列出版本链,最新的在前。POST /v2/entries/{entry_id}/revert 把旧版本的内容写成新版本,不改写历史。
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/revert" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"version_id": "ver_1a07"}'GET /v2/entries/{entry_id}/diff?from=&to= 比较两个版本,GET /v2/entries/{entry_id}/lineage 说明 Entry 从哪里来、每个版本怎样产生。按路径调用时用 GET /v2/spaces/{space_id}/files/diff 和 GET /v2/spaces/{space_id}/files/lineage。
# Compare an older version with the latest.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/diff?path=/notes/hello.md&from=ver_1a07" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
# Where the file came from, and how each version came about.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/lineage?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Agent 编辑文件时可以记录改动出自哪段对话:在主线上的 PUT 和 PATCH 带 session_id,取值与导入那段对话时相同。lineage 会显示这个版本的 session_id,之后可以用 GET /v2/entries?metadata={"session_id":"…"} 找到那段对话。
changes 报告,因此返回 200 并不保证该路径始终保持这些字节。失败的版本保留在 versions 中,状态为 discarded,可以用 version 读取它的字节,或用 revert 恢复。需要确认新版本已经生效时,请查看 knowledge.state。查看处理状态
GET /v2/entries/{entry_id}/processing 和 GET /v2/jobs/{job_id} 用于查询处理进度。POST /v2/entries/{entry_id}/reprocess 用于重试失败的版本,或重新处理最新版本。如需等待文件变为可检索或跟踪批量导入进度,见 处理进度。
删除和彻底删除
| 操作 | 效果 | 需要 | 可否撤销 |
|---|---|---|---|
DELETE 文件或 Entry | 移入废纸篓,在检索中立即不可见 | knowledge:write 和 editor | 可以,用 restore |
POST /v2/entries/{entry_id}/purge | 彻底删除 Entry、全部版本和路径 | knowledge:manage 和 Space 所有者 | 不可以 |
处理 Agent 的提案
Agent 修改不属于自己的文件时,默认返回 403 proposal_required,不产生任何内容。Space 所有者把它的 write_mode 设为 direct 后才能直接写入,见 权限。否则,Agent 可以带 Prefer: handling=proposal 把这次写入转成提案:文件保持不变,返回 202 和 proposal_id,由审核人决定。文件的 PUT 和 PATCH、files/batch、分片上传的完成请求和分支合并都支持这个请求头。
# As the Agent: propose instead of failing with 403 proposal_required.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/plan.md" \
-H "Authorization: Bearer $AGENT_KEY" \
-H "Prefer: handling=proposal" \
-H "Content-Type: text/markdown" \
--data-binary @plan.md
# As a reviewer: open proposals, what each one changes, then decide.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/proposals" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/diff" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/approve" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Agreed plan"}'- 只有在不带这个请求头会返回 403 时才生效:自己的文件和新文件照常直接写入。
- 移动、删除和恢复他人的文件、
revert以及记忆写入不能转成提案,仍返回 403。 - 审核人是 Space 所有者,以及能直接修改该文件的 editor:人类用户,和
direct模式下文件在其write_root内的 Agent。 - 提案不是版本:只有作者和 Space 所有者能在
versions中看到提案内容,检索永远不会返回它。
