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

按 id 访问的 Entry:内容、版本、处理、废纸篓和彻底删除。

列出 Entry

GET/v2/entries

调用方可见的 Entry,可用 space_id(也接受 default 或 ext:<external_id>)限定到一个 Space。记忆和 Agent 档案不在此列出。按 id 倒序排列,翻页期间次序不变。trashed=true 改为列出废纸篓中已删除且尚可恢复的 Entry,每条带 trash(删除时间及文件原路径)。q 和 state 可进一步筛选这两种列表。已彻底删除的 Entry 不在任一列表中。设有 read_root 的成员看不到废纸篓中的 Entry。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20
space_id查询DevSpaceRef只保留该 Space 的 Entry。可传 Space id、default 或 ext:<external_id>,与路径参数中的含义相同。默认 Space,和路径里的含义相同。长度 1 到 256
trashed查询booleantrue 表示列出废纸篓,而不是现有的 Entry。
metadata查询string只保留元数据里有这些值的 Entry:一个 JSON 对象,做 URL 编码,例如 {"status":"final"}。每个键都要精确相等;1 到 8 个键。键对应的值为列表时,给定值须为其中的一项。
q查询string只保留标题或文件路径包含该文本的 Entry,不区分大小写:1 到 200 个字符,按字面匹配,用于浏览而非检索。要按语义查找 Entry,请调用 search。长度 1 到 200
state查询DevKnowledgeState只保留 knowledge.state 为该值的 Entry,例如用 failed 列出已放弃处理的 Entry。

响应

  • 200 application/json
字段类型说明
data必填DevEntry[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "title": "Launch notes",
      "latest_version_id": "<latest_version_id>",
      "metadata": {},
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z",
      "file": {
        "path": "/notes/hello.md",
        "size": 1,
        "media_type": "<media_type>",
        "etag": "<etag>"
      },
      "knowledge": {
        "state": "readable"
      },
      "memory": {
        "scope": "project",
        "kind": "<kind>",
        "pinned": false,
        "exclude": false
      },
      "memory_exclude": false,
      "access": {
        "role": "owner",
        "capabilities": [
          "knowledge:read"
        ]
      }
    }
  ]
}

读取 Entry

GET/v2/entries/{entry_id}

读取一个 Entry:有路径时包含 file(路径、大小、媒体类型和 ETag),以及 latest_version_id、metadata 和 occurred_at。需要 knowledge:read。Entry 不存在或调用方不可见时返回 404 not_found。

需要的能力 knowledge:read

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

修改 Entry

PATCH/v2/entries/{entry_id}

修改 Entry 的 title、metadata、metadata_patch、memory_exclude 或 occurred_at,至少传入一项。新的 title 会写入新版本,其余字段不会。文件的标题即文件名,重命名或移动请使用 tree/operations。需要 knowledge:write。

需要的能力 knowledge:write

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

请求体

application/json DevUpdateEntryRequest 修改标题会产生新版本:标题会纳入索引,而版本不可变。标题相同时不执行任何操作。文件的标题即文件名,因此对文件传 title 返回 422,请用 tree/operations 重命名。至少传一个字段。

字段类型说明
titlestring新标题,1 到 512 个字符。不适用于文件:文件请用 tree/operations 改名。长度 1 到 512
metadataDevMetadata整体替换 Entry 的元数据:需传入所有要保留的键,传 {} 清空。不会产生新版本。对任何 Entry 都有效,文件也包括在内。Entry 重新索引后过滤即可看到变化,通常在几秒内。
metadata_patchobject按键修改元数据,而不是整体替换:带值的键被设置,值为 null 的键被删除,没提到的键保持不变。两个调用方各改不同的键不会互相覆盖。不能与 metadata 同时传入。合并后的结果仍然最多 32 个值。
memory_excludeboolean设为 true 时停用从该 Entry 提炼的事实,并停止提炼;搜索和读取不受影响。设为 false 时重新提炼,已遗忘或更正的事实不会恢复。
occurred_atstring (date-time) | null来源本身发生的时间。传入 null 将其清空,检索的时间过滤改回按 Entry 的写入时间计算。不会产生新版本;Entry 重新索引后过滤条件即可反映该变更,通常在几秒内完成。已提炼出的记忆保留其原有的时间。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X PATCH "https://api.mirabase.dev/v2/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

将 Entry 移入废纸篓

DELETE/v2/entries/{entry_id}

把 Entry 移入废纸篓。需要 knowledge:write 和至少 editor 角色,与 DELETE files 相同;Entry 是文件时,它的路径一同移入废纸篓。用 restore 恢复。第二次删除返回 404 not_found。

需要的能力 knowledge:write

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
If-Match请求头string传入一个 ETag(带引号的版本 id):不是最新版本时返回 412。或传入 *:文件或 Entry 不存在时返回 412。不传时后写覆盖。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X DELETE "https://api.mirabase.dev/v2/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "entry_id": "<entry_id>",
  "deleted": true
}

读取 Entry 内容

GET/v2/entries/{entry_id}/content

按 id 读取与 GET files 相同的视图:view=raw(默认)返回原始字节,meta 返回 Entry,其余为内容视图。从网址导入的 Entry 没有原始字节:view=raw 返回 422 view_not_available,请改用 view=text。view=raw 时 Range、If-Range 和 If-None-Match 的行为与 GET files 相同。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
view查询DevFileView返回内容的哪种形式:raw(默认)返回字节,meta 返回 Entry,text、table 或 recognized 返回处理后的视图。
version查询DevId这个 Entry 某个版本的 id,读取该版本而不是最新版本。view=meta 不支持此参数(返回 422)。长度 1 到 256
Range请求头string一个区间:bytes=0-99、bytes=100- 或 bytes=-100。仅对 view=raw 生效,其他视图忽略它。
If-Range请求头string一个 ETag。若内容已变更,则返回完整的新内容(200),而非部分区间(206)。
If-None-Match请求头string已持有的 ETag。view=raw 时,若字节未变则返回 304,不含响应体。

响应

响应头

  • ETag
  • Mirabase-Entry-Id
  • Mirabase-Version-Id
  • Mirabase-Knowledge-State
  • Last-Modified 内容最后一次变更的时间,HTTP 日期格式。仅在返回最新版本时包含。
  • Content-Range
  • Accept-Ranges

错误状态

400 401 403 404 416 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/content" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

获取 Entry 下载地址

GET/v2/entries/{entry_id}/content-url

获取 version(默认最新版本)原始字节的签名下载地址,有效期为 expires_in 秒(60 到 300,默认 300)。检查规则与 view=raw 相同;从网址导入的 Entry 返回 422 view_not_available。签发地址前会记录审计日志。原件保存在服务器上而非对象存储中时返回 409 content_url_unavailable,请改用 view=raw。503 original_unavailable 表示暂时无法签发地址,请稍后重试。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
version查询DevId要签发地址的版本的 id。默认最新版本。长度 1 到 256
expires_in查询integer地址的有效时长,单位为秒:60 到 300,默认 300。60 到 300,默认 300

响应

错误状态

400 401 403 404 409 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/content-url" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "url": "https://example.com/article",
  "method": "GET",
  "expires_at": "2026-11-06T00:00:00Z",
  "entry_id": "<entry_id>",
  "version_id": "<version_id>",
  "size_bytes": 1,
  "media_type": "<media_type>"
}

列出副本即将上线

GET/v2/entries/{entry_id}/copies

尚未上线,接口和字段可能调整。

即将上线:从该 Entry 复制产生且调用方可见的 Entry,按时间倒序排列。

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

  • 200 application/json
字段类型说明
data必填DevEntryCopy[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/copies" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "data": [
    {
      "entry_id": "<entry_id>",
      "source_version_id": "<source_version_id>",
      "space_id": "<space_id>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

比较版本

GET/v2/entries/{entry_id}/diff

比较这个 Entry 的两个版本,to 默认最新版本。版本不存在或你不可见时返回 404 not_found。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
from必填查询DevId作为比较起点的版本的 id。长度 1 到 256
to查询DevId作为比较终点的版本的 id。默认最新版本。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/diff?from=<from>" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "entry_id": "<entry_id>",
  "from_version_id": "<from_version_id>",
  "to_version_id": "<to_version_id>",
  "identical": false,
  "basis": "original"
}

查看来源

GET/v2/entries/{entry_id}/lineage

返回该 Entry 的起源(新建、复制或从分支合并)以及各个版本的产生方式,最新的在前。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/lineage" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "entry_id": "<entry_id>",
  "origin": {
    "kind": "created"
  },
  "data": [
    {
      "version_id": "<version_id>",
      "parent_version_ids": [
        "<parent_version_ids>"
      ],
      "created_at": "2026-11-06T00:00:00Z",
      "kind": "create"
    }
  ]
}

读取处理状态

GET/v2/entries/{entry_id}/processing

返回 Entry 最新版本的处理进度:status、knowledge_state、当前的 stage 及 progress,等待期间还会返回 queue;失败时返回 error。stage 为 enriching 或 ready 后,搜索即可找到该版本。写入返回 202 后可轮询此接口,或在写入时发送 Prefer: wait。同时处理大量文件时,请轮询 GET /v2/spaces/{space_id}/processing。失败的版本可用 POST .../reprocess 重试。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "entry_id": "<entry_id>",
  "version_id": "<version_id>",
  "status": "accepted",
  "knowledge_state": "readable",
  "stage": "queued",
  "progress": {
    "done": 1,
    "total": 1
  }
}

彻底删除 Entry

POST/v2/entries/{entry_id}/purge

彻底删除 Entry(无论在用还是已在废纸篓中),连同其全部版本和路径,不可撤销。需要 knowledge:manage 和 Space 所有者身份。存储配额立即返还,彻底删除由任务完成。

需要的能力 knowledge:manage

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

响应

响应头

  • Location /v2/jobs/{job_id}:轮询它,直到 status 变成 succeeded 或 failed。

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/purge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "job_id": "<job_id>"
}

重新处理 Entry

POST/v2/entries/{entry_id}/reprocess

最新版本失败时重试,否则重新处理。已有处理在进行时返回 409 job_in_flight 并附带 job_id。需要 knowledge:write。

需要的能力 knowledge:write

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

响应

响应头

  • Location /v2/jobs/{job_id}:轮询它,直到 status 变成 succeeded 或 failed。

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/reprocess" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "job_id": "<job_id>"
}

恢复 Entry

POST/v2/entries/{entry_id}/restore

恢复废纸篓里的 Entry 及其路径。路径被占用时返回 409 path_conflict,不会自动重命名。已彻底删除的 Entry 返回 409。不在废纸篓的 Entry 原样返回。需要 knowledge:write。

需要的能力 knowledge:write

指南:连接 Agent(MCP)

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/restore" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

回滚到旧版本

POST/v2/entries/{entry_id}/revert

把旧版本的内容写为新版本。不带 If-Match 时后写覆盖。回滚到最新版本时不执行任何操作。响应带新版本的 ETag,和写文件时一样。需要 knowledge:write。

需要的能力 knowledge:write

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512
If-Match请求头string传入一个 ETag(带引号的版本 id):不是最新版本时返回 412。或传入 *:文件或 Entry 不存在时返回 412。不传时后写覆盖。

请求体

application/json DevRevertRequest

字段类型说明
version_id必填DevId要回滚到的版本的 id;它的内容成为新的最新版本。

响应

响应头

  • ETag 刚写入内容的 ETag:下次写入时可传入 If-Match,无需重新读取文件。

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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":"<version_id>"}'

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

列出版本

GET/v2/entries/{entry_id}/versions

列出 Entry 的版本,最新的在前。需要 knowledge:read。

需要的能力 knowledge:read

指南:文件与版本

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

  • 200 application/json
字段类型说明
data必填DevVersion[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "data": [
    {
      "id": "<id>",
      "entry_id": "<entry_id>",
      "status": "accepted",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

读取版本

GET/v2/entries/{entry_id}/versions/{version_id}

读取 Entry 的一个版本。版本内容永不改变;处理过程中它的 status 会变。版本不存在、属于另一个 Entry 或调用方不可见时返回 404 not_found。需要 knowledge:read。

需要的能力 knowledge:read

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
version_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions/$VERSION_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "<id>",
  "entry_id": "<entry_id>",
  "status": "accepted",
  "created_at": "2026-11-06T00:00:00Z"
}

修改版本说明

PATCH/v2/entries/{entry_id}/versions/{version_id}/message

替换某个版本的说明,最多 120 个字符。说明是版本中唯一可以由你修改的部分。仅限 Space 所有者操作。需要 knowledge:write。

需要的能力 knowledge:write

参数

名称位置类型说明
entry_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
version_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

请求体

application/json DevUpdateVersionMessageRequest

字段类型说明
message必填string版本的新说明,最多 120 个字符。最长 120

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X PATCH "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions/$VERSION_ID/message" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Move the launch date"}'

响应结构示例

json
{
  "id": "<id>",
  "entry_id": "<entry_id>",
  "status": "accepted",
  "created_at": "2026-11-06T00:00:00Z"
}

清空废纸篓

POST/v2/spaces/{space_id}/trash/purge

清空该 Space 的废纸篓:相当于对废纸篓中每个可见的 Entry 执行 POST /v2/entries/{id}/purge,因此需要 knowledge:manage 和 Space 所有者身份,不可撤销,存储配额立即返还。单次调用最多处理 100 个 Entry;has_more 表示仍需继续调用,重复调用始终安全。传入 delete_batch_id 时仅清除该次删除移入废纸篓的 Entry。可先调用 GET /v2/entries?trashed=true 查看废纸篓中的内容。

需要的能力 knowledge:manage

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256

请求体

application/json DevPurgeTrashRequest

字段类型说明
delete_batch_idDevId仅彻底删除该次删除操作移除的 Entry。不传则彻底删除当前 Space 废纸篓中你可见的全部内容。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/trash/purge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

响应结构示例

json
{
  "purged": [
    {
      "entry_id": "<entry_id>",
      "job_id": "<job_id>"
    }
  ],
  "has_more": false
}