Entry
Markdown 版按 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 | 查询 | boolean | true 表示列出废纸篓,而不是现有的 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。 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevEntry[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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
参数
响应
200application/jsonDevEntry
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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
指南:文件与版本
参数
请求体
application/json DevUpdateEntryRequest 修改标题会产生新版本:标题会纳入索引,而版本不可变。标题相同时不执行任何操作。文件的标题即文件名,因此对文件传 title 返回 422,请用 tree/operations 重命名。至少传一个字段。
| 字段 | 类型 | 说明 |
|---|---|---|
title | string | 新标题,1 到 512 个字符。不适用于文件:文件请用 tree/operations 改名。长度 1 到 512 |
metadata | DevMetadata | 整体替换 Entry 的元数据:需传入所有要保留的键,传 {} 清空。不会产生新版本。对任何 Entry 都有效,文件也包括在内。Entry 重新索引后过滤即可看到变化,通常在几秒内。 |
metadata_patch | object | 按键修改元数据,而不是整体替换:带值的键被设置,值为 null 的键被删除,没提到的键保持不变。两个调用方各改不同的键不会互相覆盖。不能与 metadata 同时传入。合并后的结果仍然最多 32 个值。 |
memory_exclude | boolean | 设为 true 时停用从该 Entry 提炼的事实,并停止提炼;搜索和读取不受影响。设为 false 时重新提炼,已遗忘或更正的事实不会恢复。 |
occurred_at | string (date-time) | null | 来源本身发生的时间。传入 null 将其清空,检索的时间过滤改回按 Entry 的写入时间计算。不会产生新版本;Entry 重新索引后过滤条件即可反映该变更,通常在几秒内完成。已提炼出的记忆保留其原有的时间。 |
响应
200application/jsonDevEntry
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X PATCH "https://api.mirabase.dev/v2/entries/$ENTRY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"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。不传时后写覆盖。 |
响应
200application/jsonDevFileDeletion
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X DELETE "https://api.mirabase.dev/v2/entries/$ENTRY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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,不含响应体。 |
响应
200*/*binary,application/jsonDevEntry | DevEntryContent206*/*binary
响应头
ETagMirabase-Entry-IdMirabase-Version-IdMirabase-Knowledge-StateLast-Modified内容最后一次变更的时间,HTTP 日期格式。仅在返回最新版本时包含。Content-RangeAccept-Ranges
错误状态
400 401 403 404 416 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/content" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 |
响应
200application/jsonDevContentUrl
错误状态
400 401 403 404 409 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/content-url" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevEntryCopy[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/copies" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 |
响应
200application/jsonDevVersionDiff
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/diff?from=<from>" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 |
响应
200application/jsonDevLineage
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/lineage" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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
指南:文件与版本
参数
响应
200application/jsonDevEntryProcessing
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
响应
202application/jsonDevJobReceipt
响应头
Location/v2/jobs/{job_id}:轮询它,直到status变成succeeded或failed。
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/purge" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
响应
202application/jsonDevJobReceipt
响应头
Location/v2/jobs/{job_id}:轮询它,直到status变成succeeded或failed。
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/reprocess" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"job_id": "<job_id>"
}恢复 Entry
POST/v2/entries/{entry_id}/restore
恢复废纸篓里的 Entry 及其路径。路径被占用时返回 409 path_conflict,不会自动重命名。已彻底删除的 Entry 返回 409。不在废纸篓的 Entry 原样返回。需要 knowledge:write。
需要的能力 knowledge:write
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
entry_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
响应
200application/jsonDevEntry
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/restore" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 | 请求头 | DevIdempotencyKey | Idempotency-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;它的内容成为新的最新版本。 |
响应
200application/jsonDevEntry
响应头
ETag刚写入内容的ETag:下次写入时可传入If-Match,无需重新读取文件。
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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>"}'响应结构示例
{
"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 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevVersion[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 |
响应
200application/jsonDevVersion
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions/$VERSION_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 |
响应
200application/jsonDevVersion
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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"}'响应结构示例
{
"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必填 | 路径 | DevSpaceRef | Space 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_id | DevId | 仅彻底删除该次删除操作移除的 Entry。不传则彻底删除当前 Space 废纸篓中你可见的全部内容。 |
响应
200application/jsonDevPurgeTrashReceipt
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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 '{}'响应结构示例
{
"purged": [
{
"entry_id": "<entry_id>",
"job_id": "<job_id>"
}
],
"has_more": false
}