Skip to content
Developer docs
Docs menu

Uploads

Markdown

Multipart 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

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
branchQueryDevBranchRefThe 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.
modeQuery644 | 755The file mode, 644 or 755 (executable). With branch only.
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

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.

FieldTypeDescription
pathRequiredDevPathResolved when the upload completes, so the file may appear or change in between.
sizeRequiredintegerSize of the whole file in bytes.>= 1
media_typeRequiredstringThe file's media type, such as application/pdf.
checksum_sha256RequiredstringBase64 SHA-256 of the whole file, checked on completion.

Responses

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/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

json
{
  "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

NameInTypeDescription
upload_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

  • 204 No 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
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

NameInTypeDescription
upload_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
If-MatchHeaderstringOne 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.
PreferHeaderstringhandling=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-MatchHeaderstring* creates only; an existing file fails with 412 precondition_failed.

Request body

application/json DevCompleteUploadRequest

FieldTypeDescription
partsRequiredDevCompletedPart[]Every part of the file, each with the ETag its PUT returned.min items 1
session_idstringYour 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_atstring (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.
metadataDevMetadataReplaces the Entry's metadata as a whole, as metadata does on PATCH /v2/entries/{id}. Retrieval's filter.metadata matches it.
memory_excludebooleantrue 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

Response headers

  • ETag The ETag of what was just written: send it in If-Match on the next write without reading it again.
  • 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/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
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

json
{
  "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

NameInTypeDescription
upload_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Request body

application/json DevUploadPartsRequest

FieldTypeDescription
part_numbersRequiredinteger[]Numbered from 1.items 1..128

Responses

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/uploads/$UPLOAD_ID/parts" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"part_numbers":[1]}'

Example response

json
{
  "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>"
  }
}