# Ingest

Add a source that has no path: a URL, text, or a conversation.

API reference. Base URL: `https://api.mirabase.dev`

## Ingest a URL, text, or conversation

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

Add a source that has no path: each call creates one Entry. Ingesting the same content twice creates two Entries; use `Idempotency-Key` for retries. Needs `knowledge:write`.

**Capability** `knowledge:write`

Guide: [Files and versions](https://mirabase.io/developers/files.md#ingest)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A Space id; `default` for your default Space (your own, or the only Space you can see); or `ext:<external_id>` for the Space that carries your own id for it, such as `ext:user-42`. All three work in a path, in `?space_id=`, and in `space_ids`. An `external_id` that no visible Space carries returns 404. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | The same `Idempotency-Key`, principal, API key, operation, and input replay the original result for 24 hours. The same `Idempotency-Key` with different input returns 409 `conflict`. length 1..512 |
| `Prefer` | Header | `string` | Optional | `wait=N`, at most 10: hold the response for up to N seconds until this version finishes processing. The write is already committed, so timing out only means `knowledge.state` has not reached `indexed` yet. On `files` writes, `handling=proposal` turns a write that would be 403 `proposal_required` into a proposal (202 `DevProposalReceipt`); anywhere else it changes nothing. Other preferences are ignored. |

### Request body

`application/json` `DevIngestRequest`

### Responses

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

### Response headers

- `Preference-Applied` `wait=N` when the request waited, on operations that take `Prefer: wait`. Absent when it did not, such as when the key already has 4 requests waiting. `handling=proposal` when a write became a proposal.
- `Location` `/v2/jobs/{job_id}`: poll it until `status` is `succeeded` or `failed`.

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```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"}'
```

### Example response

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