POST /v1/items/{id}/images

Scope

write_items

Request parameters

Name	In	Type	Required	Description
id	path	string	required	ID of the target resource.
Idempotency-Key	header	string	required	Idempotency key (required). A UUID v4 is recommended. Resending the same key replays the original result, and the response carries Idempotent-Replay: true. Sending a different body with the same key returns 422, so always retry with the identical request.
source_url	body	string	required	The URL to fetch the image from. HTTPS only, JPEG or PNG, up to 2 MB. The type is determined from the actual bytes, not the file extension.
type	body	enum(main	additional)	optional
orientation	body	enum(landscape	square)	optional

Response example

{
  "item_id": "string",
  "type": "main",
  "key": "string",
  "url": "string",
  "sort": 0,
  "orientation": "landscape"
}

Description

Register or replace an item image by URL, as either the main image or an additional one. (write_items)

Error response example

{
  "error": {
    "code": "insufficient_scope",
    "message": "requires scope 'write_items'",
    "request_id": "req_01H..."
  }
}

Possible errors: 400 / 401 / 403 / 404 / 409 / 422 / 503