跳到主要内容
开发者文档
文档目录

文件与版本

Markdown 版

写入、读取、编辑和整理文件,比较和回滚版本,处理 Agent 的提案。

写入文件

PUT /v2/spaces/{space_id}/files 创建或替换一个文件,请求体即文件内容。返回时写入已提交,可以立即读取。大小上限、状态码和请求头见参考页。

curl
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。

curl
# 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 约定。

curl
# 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
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。

curl
# 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"
地址到期前,任何获得此地址的人都能下载,吊销 Key 也无法阻止,因此请像保管 Key 一样保管此地址。

管理目录

GET /v2/spaces/{space_id}/tree 列出目录。POST /v2/spaces/{space_id}/tree/operations 按顺序执行 mkdir、move、copy、delete 和 restore,全部生效或全部不生效。

curl
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 是完整的新路径。目标被占用时返回 409 path_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 约定 跟踪任务。

curl
# 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
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: *。

curl
# 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
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
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。

curl
# 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、分片上传的完成请求和分支合并都支持这个请求头。

curl
# 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 中看到提案内容,检索永远不会返回它。

下一步