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

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

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="}'

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.

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