Images and sketches
Images have dedicated endpoints so they appear in the correct photo collection or sketch group in Rechain. Use these endpoints after creating a product or colorway. Uploading through /attachments puts the file in attachments instead.
All examples use https://api.rechain.co/public/v1. For staging, replace the host with your staging backend URL and use a staging API key.
Choose the right resource
productId is a product UUID. variantId is the numeric id returned by the colorway API, not the separate colorway uuid. Image IDs and sketch group IDs are UUIDs.
Send your API key in Authorization: Bearer YOUR_API_KEY. Reads follow the credential’s product scope; uploads, edits, deletes, and reorder require permission to update products. Camel case and snake case keys are accepted.
Upload an image file
Use multipart/form-data with bracketed field names. These examples upload an image file from your computer. Let your client set the multipart Content-Type header, including its boundary.
Product photo
Colorway photo
The photo at position 0 must be a static image. GIFs can follow it. Omitting position appends after the highest existing position. Replacing a colorway file updates its contentType and revalidates the static-first rule.
Sketch in a specific group
First list the groups available for your product:
The response is an array of groups with id, name, position, and productId. A null productId means the group is company-wide. The list includes company-wide groups and groups for the requested product; component-only groups are excluded.
Pass the chosen group’s id when uploading:
Omit sketchGroupId to use the company’s Uncategorized group. A supplied group must be company-wide or belong to the same product.
Try it in Postman
- Create a
POSTrequest using the appropriate endpoint above. - Under Authorization, select Bearer Token and enter your API key.
- Under Body, select form-data.
- Add the parent field as Text, and the upload field as File, then select your image.
- Add an optional description or sketch group and click Send.
For a file named test_screenshot on your Desktop, use Postman’s file picker to select the actual image, including its extension. Do not enter the local path as a text value. Changing from photos to sketches requires changing both the endpoint and the field names.
A successful single upload returns 201 Created, including the image id, parent ID, URL, and position. The image is stored before the request returns. Product-page DPP photo copies may appear shortly afterward.
Upload from an image URL
Send application/json instead of multipart. The server downloads and stores the image in Rechain’s managed storage. Use a reachable HTTP(S) URL; private/local network URLs are blocked.
Product photo
Send this body to POST /product_photos.
Colorway photo
Send this body to POST /variant_photos.
Product sketch
Send this body to POST /product_sketches.
Send base64 image data
JSON requests can also send a complete image data URI in file for photos or photo for sketches. Include the data:image/...;base64, prefix and the full encoded image. For example, the following uploads a one-pixel PNG:
For each image, provide exactly one file/data URI or URL. Sending both file and fileUrl, or both photo and photoUrl, returns 422.
List, replace, edit, and remove images
The three image resources support the same operations:
Replace RESOURCE with product_photos, variant_photos, or product_sketches. Lists return arrays ordered by position, creation time, and ID. Use page and perPage for pagination; perPage defaults to and is capped at 200. Omitting the parent filter lists images across accessible parents.
Updates use the same singular JSON wrapper or multipart field names as create. The parent cannot be changed. Omitted fields remain unchanged. Do not send a blank image field to remove an image; use DELETE.
For example, send this body to PUT /product_photos/PHOTO_ID to replace a product photo:
For file replacements, send multipart with productPhoto[file], variantPhoto[file], or productSketch[photo] set to File. You do not need to send the parent ID again.
To move a sketch to a group, send this body to PUT /product_sketches/SKETCH_ID:
Omitting sketchGroupId on update keeps the current group; setting it to null or an empty value selects Uncategorized. Product photos and sketches also accept description. All three accept a non-negative position; setting a position does not automatically shift other images.
Single updates return 200 OK. Invalid replacements preserve the existing image. If another request changes the image while your replacement uploads, the API returns 409 Conflict; retrieve the current image and retry.
Image writes update the parent product’s updatedAt. Product responses include productPhotos and productSketches; product/colorway responses include variantPhotos. Use the dedicated image endpoints for full individual image details.
Reorder product photos
Send PUT /product_photos/reorder with every current photo ID exactly once, in the desired order:
The response is the reordered array with contiguous positions starting at zero. Duplicate, missing, or foreign photo IDs return 422 without changing the collection.
Import several images in the background
Use the bulk_create endpoint for 1–25 images. JSON uses the plural array name and no singular wrapper around each entry:
For example, import two sketches into a specific group:
Entries can mix URLs and base64 data URIs, using the correct file field for the resource. To upload several binary files, use repeated multipart field pairs with empty array brackets:
Repeat each parent/file pair in order for the next image. Postman accepts duplicate rows with the same bracketed keys in Body > form-data, with each file row set to File. For colorways, use variantPhotos[][variantId] and variantPhotos[][file]. For sketches, use productSketches[][productId], productSketches[][photo], and optional productSketches[][sketchGroupId].
The server validates the submission and stores uploaded originals, then returns 202 Accepted. Image downloads and processing happen in the background. A one-entry batch is also supported when you want an asynchronous single upload. Entries append in request order unless you provide positions.
A Location response header contains the same status URL.
Track the import
Poll GET /image_imports/IMPORT_ID with the same API credential that submitted it. Product access must still be available. When using statusUrl, append it to the API host directly; it already includes /public/v1.
results contains finished entries, identified by their zero-based index in the request array. Pending entries have no result yet. A batch can finish with partial success:
Retrieve each created image using its id and the corresponding image endpoint. Invalid image content and download failures appear per entry. Revoked access stops processing. Unfinished queued or processing imports expire after seven days; completed results and images are preserved, and staged originals are cleaned up. Import status records are retained.
Retry safely
Include an optional Idempotency-Key header, at most 200 bytes, when submitting a batch. The same credential, key, and payload return the existing import rather than creating duplicate images. Reusing a key with a different payload returns 409 Conflict. To resubmit failed entries from a terminal import, use a new key. Retrying with the old key returns that existing import.
Limits and errors
- Maximum image size: 25 MB per file or decoded data URI, including images downloaded from URLs.
- Batch size: 1–25 images.
- Total size of uploaded files in one batch: 100 MB.
- HTTP downloads allow up to three redirects, a five-second connection timeout, a ten-second read timeout, and a thirty-second deadline checked between reads and redirects. An individual network operation can run until its own timeout.
A 202 response confirms that a batch was accepted, not that every image imported successfully. Always inspect its final status and per-entry results.