Uploads
MarkdownMultipart uploads for files over 16 MiB.
Start a large upload
POST/v2/spaces/{space_id}/uploads
Start a multipart upload. Get part URLs from POST /v2/uploads/{upload_id}/parts, PUT each part, then call POST /v2/uploads/{upload_id}/complete. The same Idempotency-Key returns the same upload. With branch, completing the upload writes to that branch. Needs knowledge:write.
Capability knowledge:write
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 |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
mode | Query | 644 | 755 | The file mode, 644 or 755 (executable). With branch only. |
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 |
Request body
application/json DevCreateUploadRequest For files over 16 MiB; smaller ones go through PUT. A file over this deployment's size limit returns 413. A file too large to process is still stored and readable; its knowledge.state ends at failed.
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | Resolved when the upload completes, so the file may appear or change in between. |
sizeRequired | integer | Size of the whole file in bytes.>= 1 |
media_typeRequired | string | The file's media type, such as application/pdf. |
checksum_sha256Required | string | Base64 SHA-256 of the whole file, checked on completion. |
Responses
201application/jsonDevUpload
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/uploads" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path":"/notes/hello.md","size":1,"media_type":"<media_type>","checksum_sha256":"<checksum_sha256>"}'Example response
{
"id": "<id>",
"path": "/notes/hello.md",
"part_size": 1,
"expires_at": "2026-11-06T00:00:00Z"
}Abort an upload
POST/v2/uploads/{upload_id}/abort
Discard the uploaded parts. Aborting an aborted upload again returns 204; aborting a completed upload returns 409 upload_not_open. Needs knowledge:write.
Capability knowledge:write
Parameters
| Name | In | Type | Description |
|---|---|---|---|
upload_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
204No response body
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/uploads/$UPLOAD_ID/abort" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Complete an upload
POST/v2/uploads/{upload_id}/complete
Join the parts and write the file at its path, the same as PUT /v2/spaces/{space_id}/files. Identical content returns version_created: false. Completing again returns the same version or the same proposal. An aborted upload returns 409 upload_not_open, and one past its expires_at returns 422 upload_expired: start a new upload. A stored object whose size or media type differs from what the upload declared returns 422 upload_size_mismatch or 415 upload_media_type_mismatch, and bytes that do not hash to checksum_sha256 return 422 validation_error. Needs knowledge:write.
Capability knowledge:write
Parameters
| Name | In | Type | Description |
|---|---|---|---|
upload_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
If-Match | Header | string | One ETag (the version id in quotes): returns 412 unless it matches the latest version. Or *: returns 412 unless the file or Entry exists. Omit for last-write-wins. |
Prefer | Header | string | handling=proposal: a write that would be 403 proposal_required, an Agent in proposal mode changing a file it does not own, becomes a proposal instead. Anywhere else it changes nothing. Other preferences are ignored. |
If-None-Match | Header | string | * creates only; an existing file fails with 412 precondition_failed. |
Request body
application/json DevCompleteUploadRequest
| Field | Type | Description |
|---|---|---|
partsRequired | DevCompletedPart[] | Every part of the file, each with the ETag its PUT returned.min items 1 |
session_id | string | Your id for the conversation this file came from, as on PUT files?session_id=: it is recorded on the version this completion creates and shown by lineage. Main only: returns 422 on a branch upload.length 1..256 |
occurred_at | string (date-time) | When the file's content occurred, such as when a recording was captured. Retrieval's occurred_from and occurred_to filters use it, and passages report it; without it, they use the time the file was written. |
metadata | DevMetadata | Replaces the Entry's metadata as a whole, as metadata does on PATCH /v2/entries/{id}. Retrieval's filter.metadata matches it. |
memory_exclude | boolean | true keeps the file out of memory distillation: it is stored, indexed, and searchable, and nothing is distilled from it. false distills it again. The same switch as memory_exclude on PATCH /v2/entries/{id}. |
Responses
200application/jsonDevFileWrite | DevBranchFileWrite202application/jsonDevProposalReceipt
Response headers
ETagTheETagof what was just written: send it inIf-Matchon the next write without reading it again.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/proposals/{proposal_id}: where to read the proposal this write became.
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/uploads/$UPLOAD_ID/complete" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"parts":[{"part_number":1,"etag":"<etag>"}]}'Example response
{
"entry": {
"id": "<id>",
"space_id": "<space_id>",
"title": "Launch notes",
"latest_version_id": "<latest_version_id>",
"metadata": {},
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z",
"file": {
"path": "/notes/hello.md",
"size": 1,
"media_type": "<media_type>",
"etag": "<etag>"
},
"knowledge": {
"state": "readable"
},
"memory": {
"scope": "project",
"kind": "<kind>",
"pinned": false,
"exclude": false
},
"memory_exclude": false,
"access": {
"role": "owner",
"capabilities": [
"knowledge:read"
]
}
},
"version_id": "<version_id>",
"version_created": false
}Get part upload URLs
POST/v2/uploads/{upload_id}/parts
Get signed URLs for up to 128 parts of an upload, good for five minutes. PUT each part to its URL with the returned required_headers and keep the ETag. Parts already received are left out, so calling it again resumes. An upload that is completed or aborted returns 409 upload_not_open, and one past its expires_at returns 422 upload_expired: start a new upload. Needs knowledge:write.
Capability knowledge:write
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
upload_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Request body
application/json DevUploadPartsRequest
| Field | Type | Description |
|---|---|---|
part_numbersRequired | integer[] | Numbered from 1.items 1..128 |
Responses
200application/jsonDevUploadParts
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/uploads/$UPLOAD_ID/parts" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"part_numbers":[1]}'Example response
{
"data": [
{
"part_number": 1,
"url": "https://example.com/article"
}
],
"received": [
{
"part_number": 1,
"etag": "<etag>"
}
],
"expires_at": "2026-11-06T00:00:00Z",
"required_headers": {
"content-type": "<content-type>"
}
}