> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.rechain.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.rechain.co/_mcp/server.

# 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

| Image location   | Endpoint            | JSON wrapper    | Parent field | File field | URL field  |
| ---------------- | ------------------- | --------------- | ------------ | ---------- | ---------- |
| Product photos   | `/product_photos`   | `productPhoto`  | `productId`  | `file`     | `fileUrl`  |
| Colorway photos  | `/variant_photos`   | `variantPhoto`  | `variantId`  | `file`     | `fileUrl`  |
| Product sketches | `/product_sketches` | `productSketch` | `productId`  | `photo`    | `photoUrl` |

`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

```bash
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

```bash
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:

```bash
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:

```bash
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**.

| Resource       | Parent row (Text)          | Image row (File)       | Optional group row (Text)      |
| -------------- | -------------------------- | ---------------------- | ------------------------------ |
| Product photo  | `productPhoto[productId]`  | `productPhoto[file]`   | —                              |
| Colorway photo | `variantPhoto[variantId]`  | `variantPhoto[file]`   | —                              |
| Sketch         | `productSketch[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

```json
{
  "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

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

Send this body to `POST /variant_photos`.

### Product sketch

```json
{
  "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:

```json
{
  "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:

| Method           | Path                                     | Result                              |
| ---------------- | ---------------------------------------- | ----------------------------------- |
| `GET`            | `/product_photos?productId=PRODUCT_ID`   | Product photo array                 |
| `GET`            | `/variant_photos?variantId=201`          | Colorway photo array                |
| `GET`            | `/product_sketches?productId=PRODUCT_ID` | Product sketch array                |
| `GET`            | `/RESOURCE/IMAGE_ID`                     | One image                           |
| `PUT` or `PATCH` | `/RESOURCE/IMAGE_ID`                     | Replace the file or update metadata |
| `DELETE`         | `/RESOURCE/IMAGE_ID`                     | Remove 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:

```json
{
  "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`:

```json
{
  "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:

```json
{
  "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:

| Endpoint                             | Array key         |
| ------------------------------------ | ----------------- |
| `POST /product_photos/bulk_create`   | `productPhotos`   |
| `POST /variant_photos/bulk_create`   | `variantPhotos`   |
| `POST /product_sketches/bulk_create` | `productSketches` |

For example, import two sketches into a specific group:

```bash
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:

```bash
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.

```json
{
  "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`.

| State        | Meaning                                                 |
| ------------ | ------------------------------------------------------- |
| `queued`     | Accepted; waiting to start                              |
| `processing` | Entries are being imported                              |
| `completed`  | All entries succeeded                                   |
| `failed`     | Terminal 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:

```json
{
  "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 status | Meaning                                                                     |
| ----------- | --------------------------------------------------------------------------- |
| `201`       | Single image created                                                        |
| `200`       | Read, update, delete, or reorder succeeded                                  |
| `202`       | Batch accepted; poll its status                                             |
| `401`       | Missing, invalid, or revoked credential                                     |
| `403`       | Operation is not permitted                                                  |
| `404`       | Record is missing or outside the credential's scope                         |
| `409`       | Concurrent image edit or conflicting idempotency key                        |
| `422`       | Invalid 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.