Skip to navigation

Images and sketches

Upload product photos, colorway photos, and product 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

Image locationEndpointJSON wrapperParent fieldFile fieldURL field
Product photos/product_photosproductPhotoproductIdfilefileUrl
Colorway photos/variant_photosvariantPhotovariantIdfilefileUrl
Product sketches/product_sketchesproductSketchproductIdphotophotoUrl

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

curl -X POST 'https://api.rechain.co/public/v1/product_photos' \
-H "Authorization: Bearer $RECHAIN_API_KEY" \
-F 'productPhoto[productId]=123e4567-e89b-12d3-a456-426614174000' \
-F 'productPhoto[file]=@./front.png' \
-F 'productPhoto[description]=Front view'

Colorway photo

curl -X POST 'https://api.rechain.co/public/v1/variant_photos' \
-H "Authorization: Bearer $RECHAIN_API_KEY" \
-F 'variantPhoto[variantId]=201' \
-F 'variantPhoto[file]=@./navy-front.png'

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:

curl 'https://api.rechain.co/public/v1/sketch_groups?productId=123e4567-e89b-12d3-a456-426614174000' \
-H "Authorization: Bearer $RECHAIN_API_KEY"

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:

curl -X POST 'https://api.rechain.co/public/v1/product_sketches' \
-H "Authorization: Bearer $RECHAIN_API_KEY" \
-F 'productSketch[productId]=123e4567-e89b-12d3-a456-426614174000' \
-F 'productSketch[photo]=@./technical-front.png' \
-F 'productSketch[sketchGroupId]=123e4567-e89b-12d3-a456-426614174004' \
-F 'productSketch[description]=Technical front view'

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

  1. Create a POST request using the appropriate endpoint above.
  2. Under Authorization, select Bearer Token and enter your API key.
  3. Under Body, select form-data.
  4. Add the parent field as Text, and the upload field as File, then select your image.
  5. Add an optional description or sketch group and click Send.
ResourceParent row (Text)Image row (File)Optional group row (Text)
Product photoproductPhoto[productId]productPhoto[file]—
Colorway photovariantPhoto[variantId]variantPhoto[file]—
SketchproductSketch[productId]productSketch[photo]productSketch[sketchGroupId]

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

{
"productPhoto": {
"productId": "123e4567-e89b-12d3-a456-426614174000",
"fileUrl": "https://example.com/images/front.png",
"description": "Front view"
}
}

Send this body to POST /product_photos.

Colorway photo

{
"variantPhoto": {
"variantId": 201,
"fileUrl": "https://example.com/images/navy-front.png"
}
}

Send this body to POST /variant_photos.

Product sketch

{
"productSketch": {
"productId": "123e4567-e89b-12d3-a456-426614174000",
"photoUrl": "https://example.com/images/technical-front.png",
"sketchGroupId": "123e4567-e89b-12d3-a456-426614174004",
"description": "Technical front view"
}
}

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:

{
"productPhoto": {
"productId": "123e4567-e89b-12d3-a456-426614174000",
"file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC"
}
}

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:

MethodPathResult
GET/product_photos?productId=PRODUCT_IDProduct photo array
GET/variant_photos?variantId=201Colorway photo array
GET/product_sketches?productId=PRODUCT_IDProduct sketch array
GET/RESOURCE/IMAGE_IDOne image
PUT or PATCH/RESOURCE/IMAGE_IDReplace the file or update metadata
DELETE/RESOURCE/IMAGE_IDRemove the image

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:

{
"productPhoto": {
"fileUrl": "https://example.com/images/front-updated.png",
"description": "Updated front view"
}
}

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:

{
"productSketch": {
"sketchGroupId": "123e4567-e89b-12d3-a456-426614174004"
}
}

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:

{
"productId": "123e4567-e89b-12d3-a456-426614174000",
"photoIds": [
"123e4567-e89b-12d3-a456-426614174002",
"123e4567-e89b-12d3-a456-426614174001"
]
}

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:

EndpointArray key
POST /product_photos/bulk_createproductPhotos
POST /variant_photos/bulk_createvariantPhotos
POST /product_sketches/bulk_createproductSketches

For example, import two sketches into a specific group:

curl -X POST 'https://api.rechain.co/public/v1/product_sketches/bulk_create' \
-H "Authorization: Bearer $RECHAIN_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: sketch-import-001' \
--data '{
"productSketches": [
{
"productId": "123e4567-e89b-12d3-a456-426614174000",
"sketchGroupId": "123e4567-e89b-12d3-a456-426614174004",
"photoUrl": "https://example.com/images/technical-front.png"
},
{
"productId": "123e4567-e89b-12d3-a456-426614174000",
"sketchGroupId": "123e4567-e89b-12d3-a456-426614174004",
"photoUrl": "https://example.com/images/technical-back.png"
}
]
}'

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:

curl -X POST 'https://api.rechain.co/public/v1/product_photos/bulk_create' \
-H "Authorization: Bearer $RECHAIN_API_KEY" \
-H 'Idempotency-Key: photo-import-001' \
-F 'productPhotos[][productId]=123e4567-e89b-12d3-a456-426614174000' \
-F 'productPhotos[][file]=@./front.png' \
-F 'productPhotos[][productId]=123e4567-e89b-12d3-a456-426614174000' \
-F 'productPhotos[][file]=@./back.png'

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.

{
"id": "123e4567-e89b-12d3-a456-426614174005",
"state": "queued",
"total": 2,
"completed": 0,
"failed": 0,
"results": [],
"statusUrl": "/public/v1/image_imports/123e4567-e89b-12d3-a456-426614174005"
}

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.

StateMeaning
queuedAccepted; waiting to start
processingEntries are being imported
completedAll entries succeeded
failedTerminal failure; successful entries are still retained

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:

{
"id": "123e4567-e89b-12d3-a456-426614174005",
"state": "failed",
"total": 2,
"completed": 1,
"failed": 1,
"results": [
{ "index": 0, "state": "completed", "id": "123e4567-e89b-12d3-a456-426614174001" },
{ "index": 1, "state": "failed", "error": "Image download failed" }
],
"statusUrl": "/public/v1/image_imports/123e4567-e89b-12d3-a456-426614174005"
}

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.
HTTP statusMeaning
201Single image created
200Read, update, delete, or reorder succeeded
202Batch accepted; poll its status
401Missing, invalid, or revoked credential
403Operation is not permitted
404Record is missing or outside the credential’s scope
409Concurrent image edit or conflicting idempotency key
422Invalid parameters, failed single-image download/processing, or size limits

A 202 response confirms that a batch was accepted, not that every image imported successfully. Always inspect its final status and per-entry results.