> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nymble Commerce Images API — Upload & Manage Product Images

> REST API reference for managing product images in Nymble Commerce via the Cloudflare Images integration — upload, list, and delete product images.

Nymble Commerce uses Cloudflare Images to store and serve product images via CDN. Use the Images API to upload and manage product images. Every image you upload receives a stable, CDN-backed URL that Nymble Commerce constructs automatically — no signed URLs, no expiry, no extra configuration required.

Uploaded images are available at three sizes via their CDN base URL:

| Variant | URL suffix         |
| ------- | ------------------ |
| Small   | `{baseUrl}/small`  |
| Medium  | `{baseUrl}/medium` |
| Large   | `{baseUrl}/large`  |

All endpoints require a valid Bearer token with Admin privileges. The `OrganizationId` is read from your JWT claims.

***

## Upload images from a local file

Upload a single image file directly from your machine. Nymble Commerce stores the image in Cloudflare Images and optionally associates it with a product by SKU.

```http theme={null}
POST https://api.achievemomentum.com/api/images/from-local
Content-Type: multipart/form-data
```

### Form fields

<ParamField body="image" type="file" required>
  The image file to upload. Send as a `multipart/form-data` file part.
</ParamField>

<ParamField body="sku" type="string">
  The product SKU to associate this image with. If supplied, Nymble Commerce links the image to the matching product after upload.
</ParamField>

<ParamField body="extractSkuFromImageName" default="false" type="boolean">
  When `true`, Nymble Commerce uses the image's file name (without extension) as the SKU and attempts to find and associate the matching product automatically. Takes precedence over `sku` when both are provided.
</ParamField>

### Response

Returns `204 No Content` on success.

### Example

```bash theme={null}
# Upload and associate by explicit SKU
curl -X POST "https://api.achievemomentum.com/api/images/from-local" \
  -H "Authorization: Bearer {token}" \
  -F "image=@/path/to/widget-blue-large.jpg" \
  -F "sku=WIDGET-BLU-L" \
  -F "extractSkuFromImageName=false"
```

```bash theme={null}
# Upload and associate by extracting the SKU from the filename
# The file is named WIDGET-BLU-L.jpg, so sku = "WIDGET-BLU-L"
curl -X POST "https://api.achievemomentum.com/api/images/from-local" \
  -H "Authorization: Bearer {token}" \
  -F "image=@/path/to/WIDGET-BLU-L.jpg" \
  -F "extractSkuFromImageName=true"
```

<Tip>
  Name your image files after their product SKUs and set `extractSkuFromImageName: true` to automate product association during bulk uploads.
</Tip>

***

## Upload images from remote URLs

Provide one or more public image URLs and let Nymble Commerce fetch, process, and store them in Cloudflare Images. You can optionally associate each image with a product. This endpoint processes uploads asynchronously — it returns `204 No Content` immediately and the images become available shortly after.

```http theme={null}
POST https://api.achievemomentum.com/api/images/from-remote
```

### Body parameters

<ParamField body="images" type="array" required>
  Array of image import objects.

  <Expandable title="images[]">
    <ParamField body="imageUrl" type="string" required>
      The publicly accessible URL of the image to fetch and import.
    </ParamField>

    <ParamField body="imageName" type="string">
      A name to assign to the image in Nymble Commerce. If omitted, Nymble Commerce extracts the name from the URL path.
    </ParamField>

    <ParamField body="productSku" type="string">
      The product SKU to associate this image with after upload.
    </ParamField>

    <ParamField body="extractSkuFromImageName" default="false" type="boolean">
      When `true`, Nymble Commerce treats the `imageName` (or the name extracted from the URL) as a product SKU and attempts to associate the image automatically.
    </ParamField>
  </Expandable>
</ParamField>

### Response

Returns `204 No Content`. Image processing is asynchronous — check the [List images](#list-images) endpoint to confirm availability.

### Example

```bash theme={null}
curl -X POST "https://api.achievemomentum.com/api/images/from-remote" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      {
        "imageName": "widget-blue-large",
        "imageUrl": "https://example.com/products/widget-blue-large.jpg",
        "productSku": "WIDGET-BLU-L"
      },
      {
        "imageUrl": "https://example.com/products/WIDGET-RED-M.jpg",
        "extractSkuFromImageName": true
      },
      {
        "imageUrl": "https://example.com/products/banner.jpg"
      }
    ]
  }'
```

<Note>
  Images without a `productSku` and without `extractSkuFromImageName: true` are uploaded to your organization's image library but are not linked to any product. You can assign them later by updating the product with the image name.
</Note>

***

## Upload a category image

Upload an image to use as a category's display image. The image is stored in Cloudflare Images and the resulting URL is associated with the specified category. Pass the category name as a form field alongside the image file.

```http theme={null}
POST https://api.achievemomentum.com/api/images/category
Content-Type: multipart/form-data
```

### Form fields

<ParamField body="image" type="file" required>
  The image file to upload.
</ParamField>

<ParamField body="categoryName" type="string" required>
  The name of the category to associate this image with, e.g. `Widgets`. Spaces are converted to hyphens and the value is lowercased automatically.
</ParamField>

### Response

<ResponseField name="imageName" type="string">
  The name assigned to the uploaded image.
</ResponseField>

<ResponseField name="imageUrl" type="string">
  The CDN URL for the uploaded category image.
</ResponseField>

### Example

```bash theme={null}
curl -X POST "https://api.achievemomentum.com/api/images/category" \
  -H "Authorization: Bearer {token}" \
  -F "image=@/path/to/widgets-banner.jpg" \
  -F "categoryName=Widgets"
```

```json theme={null}
{
  "imageName": "widgets",
  "imageUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/org_4e9b7f22widgets/medium"
}
```

***

## List images

Retrieve a paginated list of all images in your organization's library, with optional filtering and sorting.

```http theme={null}
GET https://api.achievemomentum.com/api/images
```

### Query parameters

<ParamField query="pageNumber" default="1" type="integer">
  The page of results to return.
</ParamField>

<ParamField query="pageSize" default="25" type="integer">
  Number of images per page.
</ParamField>

<ParamField query="sortOn" default="Name" type="string">
  Field to sort on. Accepts `Name` or `UpdatedAt`.
</ParamField>

<ParamField query="sortDirection" default="asc" type="string">
  Sort direction. Accepts `asc` or `desc`.
</ParamField>

<ParamField query="filters" type="array">
  Optional filter objects. Filter on fields like `Name`. Supported operators: `startswith`, `contains`, `notcontains`, `endswith`, `equals`, `notequals`.
</ParamField>

### Response

Returns a paginated result containing an array of [image detail objects](#the-image-object).

### Example

```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/images?pageNumber=1&pageSize=25&sortOn=UpdatedAt&sortDirection=desc" \
  -H "Authorization: Bearer {token}"
```

```json theme={null}
{
  "data": [
    {
      "entity": {
        "id": "euoGMuxTyhp",
        "organizationId": "org_4e9b7f22",
        "name": "widget-blue-large",
        "height": 1200,
        "width": 1200,
        "contentSize": 84320.5,
        "source": "https://example.com/products/widget-blue-large.jpg",
        "format": "jpg",
        "active": true,
        "baseUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/euoGMuxTyhp/",
        "smallUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/euoGMuxTyhp/small",
        "mediumUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/euoGMuxTyhp/medium",
        "largeUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/euoGMuxTyhp/large",
        "createdAt": "2024-03-10T08:45:00Z",
        "updatedAt": "2024-03-10T08:45:00Z"
      },
      "links": [
        { "action": "GET", "href": "api/images/euoGMuxTyhp", "rel": "self" }
      ]
    }
  ],
  "totalRecords": 142,
  "currentPage": 1,
  "totalPages": 6
}
```

***

## Get an image

Retrieve a single image by its ID.

```http theme={null}
GET https://api.achievemomentum.com/api/images/{id}
```

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the image to retrieve.
</ParamField>

### Response

Returns a single [image detail object](#the-image-object).

### Example

```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/images/euoGMuxTyhp" \
  -H "Authorization: Bearer {token}"
```

```json theme={null}
{
  "id": "euoGMuxTyhp",
  "organizationId": "org_4e9b7f22",
  "name": "widget-blue-large",
  "height": 1200,
  "width": 1200,
  "contentSize": 84320.5,
  "source": "https://example.com/products/widget-blue-large.jpg",
  "format": "jpg",
  "active": true,
  "baseUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/euoGMuxTyhp/",
  "smallUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/euoGMuxTyhp/small",
  "mediumUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/euoGMuxTyhp/medium",
  "largeUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/euoGMuxTyhp/large",
  "createdAt": "2024-03-10T08:45:00Z",
  "updatedAt": "2024-03-10T08:45:00Z"
}
```

***

## Delete images

Permanently delete one or more images from your organization's library by their IDs.

```http theme={null}
DELETE https://api.achievemomentum.com/api/images
```

### Body parameters

<ParamField body="ids" type="string" required>
  A comma-separated string of image IDs to delete, e.g. `"euoGMuxTyhp,sdFg7hJkLmN"`.
</ParamField>

### Response

Returns `204 No Content` on success.

<Warning>
  Deleting images is permanent and cannot be undone. If a deleted image is referenced by a product's `images` array, that product will have broken image links. Remove the image from any product assignments before deleting.
</Warning>

### Example

```bash theme={null}
curl -X DELETE "https://api.achievemomentum.com/api/images" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": "euoGMuxTyhp,sdFg7hJkLmN"
  }'
```

***

## The image object

<ResponseField name="id" type="string">
  Cloudflare Images unique identifier for this image.
</ResponseField>

<ResponseField name="organizationId" type="string">
  The organization this image belongs to.
</ResponseField>

<ResponseField name="name" type="string">
  The image name (typically the file name without extension).
</ResponseField>

<ResponseField name="height" type="integer">
  Image height in pixels.
</ResponseField>

<ResponseField name="width" type="integer">
  Image width in pixels.
</ResponseField>

<ResponseField name="contentSize" type="number">
  File size in bytes.
</ResponseField>

<ResponseField name="source" type="string">
  The original source URL the image was imported from, or `"local"` if uploaded directly.
</ResponseField>

<ResponseField name="format" type="string">
  Image format, e.g. `jpg`, `png`, `webp`.
</ResponseField>

<ResponseField name="active" type="boolean">
  Whether this image is active.
</ResponseField>

<ResponseField name="baseUrl" type="string">
  The CDN base URL for this image. Append `/small`, `/medium`, or `/large` for the appropriate size variant.
</ResponseField>

<ResponseField name="smallUrl" type="string">
  Direct CDN URL for the small variant.
</ResponseField>

<ResponseField name="mediumUrl" type="string">
  Direct CDN URL for the medium variant.
</ResponseField>

<ResponseField name="largeUrl" type="string">
  Direct CDN URL for the large variant.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the image was uploaded.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of the most recent update.
</ResponseField>