Ingest
MarkdownAdd 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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | 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 | 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 | 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
202application/jsonDevIngestReceipt
Response headers
Preference-Appliedwait=Nwhen the request waited, on operations that takePrefer: wait. Absent when it did not, such as when the key already has 4 requests waiting.handling=proposalwhen a write became a proposal.Location/v2/jobs/{job_id}: poll it untilstatusissucceededorfailed.
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 -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
{
"entry_id": "ent_01JD2M9B2D",
"version_id": "ver_01JD2M9B2E",
"job_id": "job_01JD2M9B2F",
"knowledge": {
"state": "readable"
},
"memory_status": "confirmed",
"memory": {
"state": "pending"
},
"secrets_redacted": 0
}