Skip to content
Developer docs
Docs menu

Ingest

Markdown

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

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

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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-KeyHeaderDevIdempotencyKeyThe 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
PreferHeaderstringwait=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

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 for the error shape and Error codes for what each code means.

Example request

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

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
}