Attachments API

POST /items/attachments/bulk

Bulk Attach Legacy

Deprecated: redirects to /items/files/bulk.

Parameters

Responses

Example

curl -X POST http://localhost:8000/items/attachments/bulk \
  -H "Authorization: Bearer $TOKEN"

POST /items/files/bulk

Bulk Attach Files

Bulk-attach files from a ZIP archive via item.file.attached events. File naming convention inside the ZIP: <SKU>.jpg / .png / .webp - hero product image (first bare image per SKU) <SKU>-img-<n>.<ext> - additional product image (not hero) <SKU>-cert-<label>.<ext> - certificates tag <SKU>-doc-<label>.<ext> - certificates tag (alias for -cert-, backward compat) <SKU>-spec-<label>.<ext> - spec_sheets tag <SKU>-safety-<label>.<ext> - safety_docs tag <SKU>-360-<label>.<ext> - view_360 tag Returns: {matched, unmatched, errors, report: [{sku, file, status, url, tag, is_hero}]}

Parameters

Responses

Example

curl -X POST http://localhost:8000/items/files/bulk \
  -H "Authorization: Bearer $TOKEN"

POST /items/{entity_id}/attachments

Upload Attachment

Upload one file and attach it to an item. Pass ?attachment_type=view_360 to tag a 360 image/video explicitly.

Parameters

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/attachments \
  -H "Authorization: Bearer $TOKEN"

DELETE /items/{entity_id}/attachments/{att_id}

Delete Attachment

Remove one attachment from an item.

Parameters

Responses

Example

curl -X DELETE http://localhost:8000/items/:entity_id/attachments/:att_id \
  -H "Authorization: Bearer $TOKEN"

PUT /items/{entity_id}/attachments/{att_id}/preview

Set Preview Image

Explicitly set preview_image_id for an item. The referenced attachment must exist and have type == "image". Returns {"preview_image_id": att_id}.

Parameters

Responses

Example

curl -X PUT http://localhost:8000/items/:entity_id/attachments/:att_id/preview \
  -H "Authorization: Bearer $TOKEN"

POST /items/{entity_id}/files

Upload Item File

Upload a file and attach it to an item via item.file.attached event.

Parameters

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/files \
  -H "Authorization: Bearer $TOKEN"

GET /items/{entity_id}/files/{file_id}

Download Item File

Parameters

Responses

Example

curl -X GET http://localhost:8000/items/:entity_id/files/:file_id \
  -H "Authorization: Bearer $TOKEN"

DELETE /items/{entity_id}/files/{file_id}

Delete Item File

Parameters

Responses

Example

curl -X DELETE http://localhost:8000/items/:entity_id/files/:file_id \
  -H "Authorization: Bearer $TOKEN"

PATCH /items/{entity_id}/files/{file_id}/description

Update Item File Description

Parameters

Responses

Example

curl -X PATCH http://localhost:8000/items/:entity_id/files/:file_id/description \
  -H "Authorization: Bearer $TOKEN"

POST /items/{entity_id}/files/{file_id}/hero

Set Item File Hero

Mark a file as the hero (featured) image. Must be an image MIME type.

Parameters

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/files/:file_id/hero \
  -H "Authorization: Bearer $TOKEN"

POST /items/{entity_id}/files/{file_id}/tag

Tag Item File

Parameters

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/files/:file_id/tag \
  -H "Authorization: Bearer $TOKEN"