# Uploads

Multipart uploads for files over 16 MiB.

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

## Start a large upload

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

Start a multipart upload. Get part URLs from [`POST /v2/uploads/{upload_id}/parts`](https://mirabase.io/developers/api/uploads.md#uploads-parts), `PUT` each part, then call [`POST /v2/uploads/{upload_id}/complete`](https://mirabase.io/developers/api/uploads.md#uploads-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 | 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 |
| `branch` | Query | `DevBranchRef` | Optional | 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` | Optional | The file mode, `644` or `755` (executable). With `branch` only. |
| `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 |

### 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 | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | Resolved when the upload completes, so the file may appear or change in between. |
| `size` | `integer` | Required | Size of the whole file in bytes. >= 1 |
| `media_type` | `string` | Required | The file's media type, such as `application/pdf`. |
| `checksum_sha256` | `string` | Required | Base64 SHA-256 of the whole file, checked on completion. |

### Responses

- `201` `application/json` `DevUpload`

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `upload_id` | Path | `DevId` | Required | Opaque 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](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/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`](https://mirabase.io/developers/api/files.md#files-write). 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 | Required | Description |
| --- | --- | --- | --- | --- |
| `upload_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `If-Match` | Header | `string` | Optional | 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` | Optional | `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` | Optional | `*` creates only; an existing file fails with 412 `precondition_failed`. |

### Request body

`application/json` `DevCompleteUploadRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `parts` | `DevCompletedPart[]` | Required | Every part of the file, each with the `ETag` its `PUT` returned. min items 1 |
| `session_id` | `string` | Optional | 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)` | Optional | 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` | Optional | Replaces the Entry's metadata as a whole, as `metadata` does on [`PATCH /v2/entries/{id}`](https://mirabase.io/developers/api/entries.md#entries-update). Retrieval's `filter.metadata` matches it. |
| `memory_exclude` | `boolean` | Optional | `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}`](https://mirabase.io/developers/api/entries.md#entries-update). |

### Responses

- `200` `application/json` `DevFileWrite | DevBranchFileWrite`
- `202` `application/json` `DevProposalReceipt`

### 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](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/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](https://mirabase.io/developers/files.md#uploads)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `upload_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Request body

`application/json` `DevUploadPartsRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `part_numbers` | `integer[]` | Required | Numbered from 1. items 1..128 |

### Responses

- `200` `application/json` `DevUploadParts`

### 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/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>"
  }
}
```
