---
title: "Vimond Image Service API — compact index for LLMs"
description: "Compact index of every operation in the Vimond Image Service (client retrieval, admin, cache invalidation). Not part of the Management API in the 2.0 platform."
---

<!-- /openapi/image-service.llms.md — generated from /openapi/image-service.yaml; do not edit by hand -->

# Vimond Image Service API — compact index for LLMs

> One block per operation: method, path, `operationId`, tag, auth, and a one-line summary. **Not part of the Management API** in the 2.0 platform — use this spec for image retrieval and image-pack admin.

- **Per-tag slices:** `/openapi/image-service/tags/<slug>.openapi.yml` — see [Tags overview](#tags-overview) below.
- Canonical OpenAPI YAML: `/openapi/image-service.yaml` (~40 KB)
- Interactive Scalar reference: `/reference/image-service/`
- Guides: [image-service](/docs/image-service/), [image-management](/docs/image-management/), [image-urls-and-parameters](/docs/image-urls-and-parameters/)

## API basics

- **Client (image serving):** `https://{tenant}.image-service.{environment}.vmnd.tv/api/v2/img/{imagePackId}` — public; optional `X-vimond-access-key` on some tenants. Served by the image handler (CloudFront + Lambda) in 2.0.
- **Admin (management):** `https://{tenant}.image-service.{environment}.vmnd.tv/adminAPI/...` — Bearer JWT (`VimondAuth`). Upload originals, configure locations and crop info.
- **Cache invalidation:** `DELETE https://manage.api.{environment}.vmnd.tv/{environment}-lof/images/{tenant}/{imagePackId}` — unified platform API; see [image-cache-invalidation](/docs/image-cache-invalidation/).
- **Media type:** JSON on admin endpoints; image bytes on `GET /api/v2/img/...`.

## Concepts

| Term | Meaning |
|------|---------|
| `imagePackId` | Group of originals; referenced from assets/categories |
| `location` | Named variant slot (`main`, `thumb`, `portal-cover`, …) |
| `cropInfo` | Relative crop rectangle on a pack location |
| `resize-mode` | `crop` (default) or `includeAll` (pad with transparency) |

## Tags overview

| Tag | Operations | Per-tag slice | Description |
|-----|------------|---------------|-------------|
| Status | 2 | [`openapi/image-service/tags/status.openapi.yml`](/openapi/image-service/tags/status.openapi.yml) | Liveness and version endpoints for the image-service deployment. |
| Image retrieval | 1 | [`openapi/image-service/tags/image-retrieval.openapi.yml`](/openapi/image-service/tags/image-retrieval.openapi.yml) | End-user image fetching. |
| Public reference data | 3 | [`openapi/image-service/tags/public-reference-data.openapi.yml`](/openapi/image-service/tags/public-reference-data.openapi.yml) | Read-only views of the tenant's image locations and publishing regions. |
| Image location configs (admin) | 5 | [`openapi/image-service/tags/image-location-configs-admin.openapi.yml`](/openapi/image-service/tags/image-location-configs-admin.openapi.yml) | Tenant-wide image location definitions (`main`, `thumb`, `portal-cover`, …) with default size, resize gravity, fallback, and resize-include-all behavior. |
| Image packs (admin) | 5 | [`openapi/image-service/tags/image-packs-admin.openapi.yml`](/openapi/image-service/tags/image-packs-admin.openapi.yml) | CRUD for the image-pack record itself (without the binary). |
| Pack image locations (admin) | 4 | [`openapi/image-service/tags/pack-image-locations-admin.openapi.yml`](/openapi/image-service/tags/pack-image-locations-admin.openapi.yml) | Per-(pack, location) overrides: `cropInfo`, `useResizeIncludeAll`, `resizeGravity`, and (when supported) region-specific variants. |
| Image uploads (admin) | 3 | [`openapi/image-service/tags/image-uploads-admin.openapi.yml`](/openapi/image-service/tags/image-uploads-admin.openapi.yml) | Get image bytes into the service either by direct upload (`multipart/form-data`) or by giving the service a URL to fetch from. |
| Regions (admin) | 2 | [`openapi/image-service/tags/regions-admin.openapi.yml`](/openapi/image-service/tags/regions-admin.openapi.yml) | Geographic publishing regions. |
| Cache invalidation | 1 | [`openapi/image-service/tags/cache-invalidation.openapi.yml`](/openapi/image-service/tags/cache-invalidation.openapi.yml) | Drop the CloudFront and S3 variant caches for a specific (tenant, imagePack). |

## Operations

### Tag: Status (2)

**Per-tag slice:** [`/openapi/image-service/tags/status.openapi.yml`](/openapi/image-service/tags/status.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

Liveness and version endpoints for the image-service deployment. Useful for health-checks and as a probe for the chosen hostname.

#### GET /api/ping — `listPing`
**Tag:** Status • **Auth:** public • **Responses:** 200
**Ping**
Returns `pong` when the service is responding.

#### GET /api/systemsCheck — `listSystemsCheck`
**Tag:** Status • **Auth:** public • **Responses:** 200, 503
**Systems check**
Liveness probe that also exercises image-store and datastore connectivity.

### Tag: Image retrieval (1)

**Per-tag slice:** [`/openapi/image-service/tags/image-retrieval.openapi.yml`](/openapi/image-service/tags/image-retrieval.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

End-user image fetching. The single `GET /api/v2/img/{imagePackId}` endpoint is served by the [image handler](https://github.com/vimond/vimond-image-handler) (CloudFront + S3 + failover Lambda) in the 2.0 platform — see [Image URLs and parameters](/docs/image-urls-and-parameters/) for the full query reference.

#### GET /api/v2/img/{imagePackId} — `getImage`
**Tag:** Image retrieval • **Auth:** public • **Responses:** 200, 301, 302, 403, 404, 422
path: imagePackId • query: location, width, height, resize-mode, resize-gravity, rounded-corners, skip-crop, location-ratio, format, region, date • headers: X-vimond-access-key
**Get image variant**
Returns a binary image variant for an image pack.

### Tag: Public reference data (3)

**Per-tag slice:** [`/openapi/image-service/tags/public-reference-data.openapi.yml`](/openapi/image-service/tags/public-reference-data.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

Read-only views of the tenant's image locations and publishing regions. Mirrors the admin-side configuration so clients can validate or enumerate available locations and regions without admin auth.

#### GET /api/v2/imageLocationConfigs — `listClientImageLocationConfigs`
**Tag:** Public reference data • **Auth:** public • **Responses:** 200
headers: Accept
**List image location configs (public)**
Read-only view of the tenant's image location configs. Mirrors the admin endpoint's response shape, exposed to client apps so they can enumerate available `?location=` values.

#### GET /api/v2/regions — `listClientRegions`
**Tag:** Public reference data • **Auth:** public • **Responses:** 200
headers: Accept
**List regions (public)**
Read-only list of regions configured on this tenant.

#### GET /api/v2/regions/{region} — `getClientRegion`
**Tag:** Public reference data • **Auth:** public • **Responses:** 200, 404
path: region • headers: Accept
**Get region (public)**

### Tag: Image location configs (admin) (5)

**Per-tag slice:** [`/openapi/image-service/tags/image-location-configs-admin.openapi.yml`](/openapi/image-service/tags/image-location-configs-admin.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

Tenant-wide image location definitions (`main`, `thumb`, `portal-cover`, …) with default size, resize gravity, fallback, and resize-include-all behavior. Changing a location's size or resize policy invalidates every previously generated variant — see [Image location configs](/docs/image-location-configs/).

#### GET /adminAPI/imageLocationConfig/{name} — `getImageLocationConfig`
**Tag:** Image location configs (admin) • **Auth:** VimondAuth • **Responses:** 200, 404
path: name • headers: Accept
**Get image location config**

#### PUT /adminAPI/imageLocationConfig/{name} — `saveImageLocationConfig`
**Tag:** Image location configs (admin) • **Auth:** VimondAuth • **Responses:** 200, 409
path: name • query: force • headers: Accept, Content-Type
**Create or replace an image location config**
Use `?force=true` when changing pixel size or resize behavior so the server may invalidate variants.

#### PUT /adminAPI/imageLocationConfig/{name}/label — `saveImageLocationConfigLabel`
**Tag:** Image location configs (admin) • **Auth:** VimondAuth • **Responses:** 200
path: name • headers: Content-Type
**Update only the label of an image location config**
Lightweight cosmetic update — never requires `?force=true` because no variant is affected.

#### GET /adminAPI/imageLocationConfigs — `listImageLocationConfigs`
**Tag:** Image location configs (admin) • **Auth:** VimondAuth • **Responses:** 200
headers: Accept
**List image location configs**

#### PUT /adminAPI/imageLocationConfigs — `replaceImageLocationConfigs`
**Tag:** Image location configs (admin) • **Auth:** VimondAuth • **Responses:** 200, 400, 409
query: force • headers: Accept, Content-Type
**Replace all image location configs**
Bulk replace — anything not present in the payload is removed.

### Tag: Image packs (admin) (5)

**Per-tag slice:** [`/openapi/image-service/tags/image-packs-admin.openapi.yml`](/openapi/image-service/tags/image-packs-admin.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

CRUD for the image-pack record itself (without the binary). Image packs are referenced from assets and categories via `imagePackId`. See [Image packs](/docs/image-packs/).

#### PUT /adminAPI/copyImagePacks — `copyImagePacks`
**Tag:** Image packs (admin) • **Auth:** VimondAuth • **Responses:** 202
headers: Accept, Content-Type
**Copy image packs in bulk**
Bulk-copy image packs across tenants or environments. Body shape is `{ sourceTenant, targetTenant, imagePackIds: [...] }`.

#### GET /adminAPI/imagePack/{id} — `getImagePack`
**Tag:** Image packs (admin) • **Auth:** VimondAuth • **Responses:** 200, 404
path: id • headers: Accept
**Get an image pack**

#### PUT /adminAPI/imagePack/{id} — `updateImagePack`
**Tag:** Image packs (admin) • **Auth:** VimondAuth • **Responses:** 200
path: id • headers: Accept, Content-Type
**Update image pack metadata**
Replaces the pack metadata (not the originals). Send the full pack representation; omitted fields are cleared.

#### GET /adminAPI/imagePacks — `listImagePacks`
**Tag:** Image packs (admin) • **Auth:** VimondAuth • **Responses:** 200
query: offset • headers: Accept
**List image pack IDs**
Returns at most 1000 pack IDs. Increment `offset` to paginate.

#### POST /adminAPI/imagePacks — `createImagePack`
**Tag:** Image packs (admin) • **Auth:** VimondAuth • **Responses:** 200
headers: Accept, Content-Type
**Create an image pack**
Creates a new pack and returns the canonical `id`. Bind the returned ID to an asset by setting the asset's `imagePackId` via the REST API (see [Image packs → Binding](/docs/image-packs/#binding-a-pack-to-an-asset--category)).

### Tag: Pack image locations (admin) (4)

**Per-tag slice:** [`/openapi/image-service/tags/pack-image-locations-admin.openapi.yml`](/openapi/image-service/tags/pack-image-locations-admin.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

Per-(pack, location) overrides: `cropInfo`, `useResizeIncludeAll`, `resizeGravity`, and (when supported) region-specific variants. See [Image packs → Setting crop info](/docs/image-packs/#setting-crop-info).

#### GET /adminAPI/imagePack/{id}/{imageLocationName} — `getImagePackLocation`
**Tag:** Pack image locations (admin) • **Auth:** VimondAuth • **Responses:** 200, 404
path: id, imageLocationName • headers: Accept
**Get a pack's location settings**

#### PUT /adminAPI/imagePack/{id}/{imageLocationName} — `updateImagePackLocation`
**Tag:** Pack image locations (admin) • **Auth:** VimondAuth • **Responses:** 200
path: id, imageLocationName • headers: Accept, Content-Type
**Update a pack's location settings**
Set or clear per-location overrides on this pack, including `cropInfo`. Sending `{}` clears the overrides.

#### PUT /adminAPI/imagePack/{id}/{imageLocationName}/{region} — `updateImagePackLocationForRegion`
**Tag:** Pack image locations (admin) • **Auth:** VimondAuth • **Responses:** 200
path: id, imageLocationName, region • headers: Accept, Content-Type
**Update a pack's location settings for a specific region**
Region-keyed variant of `updateImagePackLocation`. Used when the tenant publishes different imagery per region.

#### POST /adminAPI/imagePack/{id}/deleteImageLocation — `deleteImagePackLocation`
**Tag:** Pack image locations (admin) • **Auth:** VimondAuth • **Responses:** 200
path: id • headers: Content-Type
**Remove a location from a pack**
Drops the per-(pack, location) entry — including the original and any `cropInfo`. The pack continues to exist; client requests for that location fall back to the pack's main image (or the location's configured `fallback`).

### Tag: Image uploads (admin) (3)

**Per-tag slice:** [`/openapi/image-service/tags/image-uploads-admin.openapi.yml`](/openapi/image-service/tags/image-uploads-admin.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

Get image bytes into the service either by direct upload (`multipart/form-data`) or by giving the service a URL to fetch from. See [Image packs → Uploading originals](/docs/image-packs/#uploading-originals).

#### GET /adminAPI/image/{imageId} — `getImageData`
**Tag:** Image uploads (admin) • **Auth:** VimondAuth • **Responses:** 200, 404
path: imageId
**Download stored original by image ID**
Returns the raw bytes of an original. The `imageId` is the identifier of an individual stored file (found at `imagePack.imageLocations.<name>.imageId`), not the pack ID.

#### POST /adminAPI/imagePack/{id}/{imageLocationName}/fetchImage — `fetchImagePackLocationImage`
**Tag:** Image uploads (admin) • **Auth:** VimondAuth • **Responses:** 200, 422
path: id, imageLocationName • query: imageUrl
**Fetch original from a URL for (pack, location)**
Tell the service to download the image from `imageUrl` and store it as the original for this (pack, location). Useful for ingest pipelines where the source already lives at a reachable URL.

#### POST /adminAPI/imagePack/{id}/{imageLocationName}/upload — `uploadImagePackLocationImage`
**Tag:** Image uploads (admin) • **Auth:** VimondAuth • **Responses:** 200, 422
path: id, imageLocationName
**Upload original for (pack, location)**
Upload binary image bytes for this pack at this location. The original is stored in S3 and resized on demand at serve time.

### Tag: Regions (admin) (2)

**Per-tag slice:** [`/openapi/image-service/tags/regions-admin.openapi.yml`](/openapi/image-service/tags/regions-admin.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

Geographic publishing regions. Only relevant for tenants that use region-keyed imagery. See [Image management](/docs/image-management/).

#### POST /adminAPI/regions — `createRegion`
**Tag:** Regions (admin) • **Auth:** VimondAuth • **Responses:** 200
headers: Accept, Content-Type
**Create a region**

#### PUT /adminAPI/regions/{region} — `updateRegion`
**Tag:** Regions (admin) • **Auth:** VimondAuth • **Responses:** 200
path: region • headers: Accept, Content-Type
**Update a region**

### Tag: Cache invalidation (1)

**Per-tag slice:** [`/openapi/image-service/tags/cache-invalidation.openapi.yml`](/openapi/image-service/tags/cache-invalidation.openapi.yml) — self-contained OpenAPI for just this tag's operations and the schemas they reference.

Drop the CloudFront and S3 variant caches for a specific (tenant, imagePack). Issued through the unified platform API on `manage.api.{environment}.vmnd.tv` — not under the image-service host. The normal pipeline aggregates and invalidates automatically within \~5 minutes of an admin write; use this endpoint only when you cannot wait. See [Image cache invalidation](/docs/image-cache-invalidation/).

#### DELETE /{environment}-lof/images/{tenant}/{imagePackId} — `invalidateImagePackCache`
**Tag:** Cache invalidation • **Auth:** VimondAuth • **Responses:** 204, 404
path: environment, tenant, imagePackId
**Force-invalidate a pack's CDN and S3 variant caches**
Drops the CloudFront cache entries and S3 cached variants for `(tenant, imagePackId)`. Use this only when you cannot wait for the automatic 5-minute aggregator — see [Image cache invalidation](/docs/image-cache-invalidation/).

---

_Generated from `/openapi/image-service.yaml` — 26 operations across 9 tags. Re-run `npm run openapi-derivatives` to refresh._