# 导入

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

API 参考。Base URL：`https://api.mirabase.dev`

## 导入网址、文本或对话

`POST /v2/spaces/{space_id}/ingest`

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

**需要的能力** `knowledge:write`

指南：[文件与版本](https://mirabase.io/zh/developers/files.md#ingest)

### 参数

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

### 请求体

`application/json` `DevIngestRequest`

### 响应

- `202` `application/json` `DevIngestReceipt`

### 响应头

- `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` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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
}
```
