# Upload image

`upload_image`

| Through | Form |
|---|---|
| HTTP | `POST https://api.markdownbrain.ai/v1/images` |
| MCP | tool `upload_image` |
| CLI | `mdbrain call upload_image` |

Upload an image into a workspace, either base64-encoded in `data_base64` or staged beforehand with [`begin_upload`](/docs/operations/begin_upload) and named by `upload_id` (for an image of any size). Say where with `parent_path` (a folder path; "" or omitted means the workspace root) or with `parent_id`. Returns the new file id and its path; reference it in markdown as ![alt](<name>).

**Who may call it:** agents and people.

**Writes:** yes.

## Arguments

| Name | Type | Required | Travels in | Description |
|---|---|---|---|---|
| `workspace_id` | string | yes | JSON body | The workspace to upload the image into |
| `parent_id` | string or null | no | JSON body | Folder id, or null/omitted for the workspace root |
| `parent_path` | string | no | JSON body | Folder path; "" or omitted means the workspace root |
| `name` | string | yes | JSON body | Filename with extension, e.g. diagram.png |
| `data_base64` | string | no | JSON body | The image bytes, base64-encoded — or use upload_id |
| `upload_id` | string | no | JSON body | A staged image from begin_upload, sent and not yet committed — instead of the bytes in the call |
| `content_type` | string | no | JSON body | MIME type; inferred from the extension if omitted |

## Success

`201` with `application/json`.

## Example request

```sh
curl -X POST https://api.markdownbrain.ai/v1/images \
  -H "Authorization: Bearer $MDBRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id":"00000000-0000-4000-8000-000000000010","parent_path":"specs","name":"onboarding-flow.png","data_base64":"iVBORw0KGgo="}'
```

```sh
mdbrain call upload_image \
  --workspace-id 00000000-0000-4000-8000-000000000010 \
  --parent-path specs \
  --name onboarding-flow.png \
  --data-base64 iVBORw0KGgo=
```

## Example response

> Written from the code rather than captured from a call.

```json
{
  "file_id": "00000000-0000-4000-8000-000000000106",
  "name": "onboarding-flow.png",
  "path": "specs/onboarding-flow.png",
  "url": "https://example.supabase.co/storage/v1/object/sign/images/onboarding-flow.png?token=eyJhbGciOiJIUzI1NiJ9.placeholder"
}
```

## Refusals

A refusal is a status code with `{ error: { code, message } }`. See [Errors](/docs/errors).