Copy a product photo from a remote URL into Arcus storage
Downloads an image from the supplied source_url and stores an
Arcus-owned copy in your entity’s file storage. The photo then appears
in BOTH File Management (as a documents record with
category: product_image) AND on the product’s photo gallery.
Behaves exactly like uploading a photo through the Arcus UI: the bytes are copied server-side into Arcus S3, never referenced from the external URL. This is the canonical endpoint for migrating product imagery off a legacy storefront CDN.
Idempotent: a re-POST with the same external_source + external_id
(or the same source_url when no provenance is supplied) re-uses the
existing stored image instead of creating a duplicate.
Requires products:write scope.
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Headers
Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.
255Path Parameters
UUID of the product to attach the photo to.
Body
Absolute URL of the image to copy. Max 20 MB. JPEG / PNG / WebP.
"https://cdn.example.com/products/widget-front.jpg"
Alt text for the image; defaults to the product title.
Display order of the image within the gallery.
Whether this image is the product's primary photo.
Source-system tag for historical migration (e.g. 'bubble_io', 'versa_cloud'). Used for idempotency.
Source-system image id, persisted for traceability and idempotency.
Response
Image copied into Arcus storage and attached to the product.

