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

添加没有路径的来源:网址、文本或对话。

导入网址、文本或对话

POST/v2/spaces/{space_id}/ingest

添加没有路径的来源:每次调用创建一个 Entry。相同内容导入两次会创建两个 Entry;重试请使用 Idempotency-Key。需要 knowledge:write。

需要的能力 knowledge:write

指南:文件与版本

参数

名称位置类型说明
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
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512
Prefer请求头stringwait=N(最大 10):最多等待 N 秒,直至该版本处理完成。写入已提交,等待超时仅表示 knowledge.state 尚未达到 indexed。在 files 写入上,handling=proposal 把本该返回 403 proposal_required 的写入变成提案(202 DevProposalReceipt);其他情况下不起作用。其他偏好会被忽略。

请求体

application/json DevIngestRequest

响应

响应头

  • Preference-Applied 在接受 Prefer: wait 的操作上,请求实际发生等待时返回 wait=N;未等待时不返回(例如该 Key 已有 4 个等待中的请求)。写入转为提案时返回 handling=proposal。
  • 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/spaces/$SPACE_ID/ingest" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"url","url":"https://example.com/article"}'

响应结构示例

json
{
  "entry_id": "ent_01JD2M9B2D",
  "version_id": "ver_01JD2M9B2E",
  "job_id": "job_01JD2M9B2F",
  "knowledge": {
    "state": "readable"
  },
  "memory_status": "confirmed",
  "memory": {
    "state": "pending"
  },
  "secrets_redacted": 0
}