Start a catalog photo upload
POST/v1/catalog/entities/{entityId}/images
Reserves a photo for a catalog entry and returns a single-use upload URL (valid 2 hours). Then PUT the image's bytes to upload.url with exactly upload.headers — no Authorization header — and call POST /catalog/entities/{entityId}/images/{assetId}/complete to attach it. Up to 15 MB; PNG, JPEG, WebP, AVIF or GIF. bymundi stores its own re-encoded copy (WebP, at most 2000 px on the longest side, no EXIF).
Permissions: catalog:write · Kind: write · Cost: 1 unit · MCP tool start_catalog_image_upload
Cannot be undone.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
entityId |
uuid | yes |
Body
| Field | Type | Required | Description |
|---|---|---|---|
mimeType |
"image/png" | "image/jpeg" | "image/webp" | "image/avif" | "image/gif" | yes | The image's type — only these are accepted. |
byteSize |
integer | yes | The file's size in bytes (at most 15 MB). 1–15728640 |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
object |
"catalog_image_upload" | yes | |
entityId |
uuid | yes | |
assetId |
uuid | yes | |
upload |
object | yes | |
upload.method |
"PUT" | yes | |
upload.url |
uri | yes | Single-use: PUT the image's bytes here once. |
upload.headers |
object | yes | Send exactly these headers with the PUT. |
upload.expiresAt |
string | yes |
Errors
Errors are problem details. Besides the refusals described above, any call like this one can return:
invalid_request— Invalid requestunauthorized— Missing or invalid API keyinsufficient_scope— Missing permissionrate_limited— Rate limit reachednot_found— Not foundidempotency_key_reused— Idempotency-Key reusedrequest_in_progress— Request in progress