# Get Image

In DAM, images are identified by their filename (`reference`), which is unique per tenant.
Use this endpoint to retrieve a specific image when you already know its filename.
## Authentication
Requires a valid API key in the `X-API-KEY` header.
## Example

```
GET /images(product-main-front.jpg)
X-API-KEY: your-api-key-here
```
## Response (200 OK)
The image is wrapped in the house entity envelope — its fields are under `value`, never at the
top level:

```json
{
  "value": {
    "id": 42,
    "reference": "product-main-front.jpg",
    "numLinks": 3,
    "status": "Ok",
    "modifiedOn": "2024-04-05T08:44:33",
    "fileType": "jpg",
    "createdOn": "2024-04-05T08:44:33",
    "tags": ["animales", "mascotas"],
    "originalUrl": "https://cdn.example.com/product-main-front.jpg",
    "thumbnailUrl": "https://cdn.example.com/product-main-front_TH.jpg",
    "thumbnailMediumUrl": "https://cdn.example.com/product-main-front_THM.jpg",
    "thumbnailPreviewUrl": "https://cdn.example.com/product-main-front_THP.jpg",
    "width": 800,
    "height": 600,
    "sizeInBytes": 102400
  },
  "@readLink": "https://api2.saleslayer.com/dam/images(product-main-front.jpg)",
  "@editLink": "https://api2.saleslayer.com/dam/images(product-main-front.jpg)"
}
```
Notes on the payload:
- `status` tells you whether the image is usable yet — see the status values documented on
`GET /images`. A freshly created or substituted image is `Up` until the worker finishes.
- `width`, `height` and `sizeInBytes` come from the stored metadata and are `0` until processing
has recorded them; the thumbnail URLs are empty until the renditions exist.
- `tags` is stored as a comma-separated string, so a tag that itself contains a comma comes back
split into several tags.
- `@readLink` and `@editLink` are the canonical URL of this image (this request, echoed back), and
are only emitted when hypermedia enrichment is configured for the deployment.

## Error Responses
- **401 Unauthorized**: Missing or invalid API key. Returned by the API gateway as
`{ "message": "Unauthorized", "request_id": "d8aafa5b8f3e400b60bea0123dd33317" }`
- **403 Forbidden**: The API key does not have read permissions for this operation. Same body
shape as the 401
- **404 Not Found**: No image with the given reference exists for this tenant. The body is the
message string, e.g. `"Image with reference 'missing.jpg' not found"`
- **500 Internal Server Error**: Technical error (e.g. database unavailable)

Endpoint: GET /images({reference})
Version: 2.0.0

## Path parameters:

  - `reference` (string, required)
    Image filename, unique per tenant (e.g. `product-main-front.jpg`)

## Header parameters:

  - `X-API-KEY` (string, required)
    Tenant's API key (required)

## Response 200 fields (application/json):

  - `value` (object)
    An image asset.

  - `value.id` (integer)
    Internal numeric identifier. Not stable as a public key — address images by `reference`.

  - `value.reference` (string)
    The image's filename, unique per tenant. This is the public key used to address the image and the
value entities use to reference it.

  - `value.numLinks` (integer)
    Number of entities (products, variants, categories, …) currently using this image.

  - `value.status` (string)
    Processing status: `Vd` (void), `Up` (uploading/updating), `Ok` (ready to use),
`Re` (reprocessing), `Er` (processing failed) or `Dv` (deleted). Only `Ok`
guarantees the renditions exist.

  - `value.modifiedOn` (string)
    When the image was last modified.

  - `value.fileType` (string)
    File extension of the image, without the dot (e.g. `jpg`, `png`). Derived from the
filename, not from the served Content-Type.

  - `value.createdOn` (string)
    When the image was created. Null for images predating creation-date tracking.

  - `value.tags` (array)
    Tags assigned to the image. Stored as a comma-separated string, so a tag containing a comma is
read back as several tags. Not usable in `$filter` or `$orderby`.

  - `value.originalUrl` (string)
    URL of the original, full-size image. Empty until processing has run.

  - `value.thumbnailUrl` (string)
    URL of the small thumbnail rendition. Empty until processing has generated it.

  - `value.thumbnailMediumUrl` (string)
    URL of the medium thumbnail rendition. Empty until processing has generated it.

  - `value.thumbnailPreviewUrl` (string)
    URL of the preview thumbnail rendition. Empty until processing has generated it.

  - `value.width` (integer)
    Width of the image in pixels; `0` until processing has recorded it. Not usable in
`$filter` or `$orderby`.

  - `value.height` (integer)
    Height of the image in pixels; `0` until processing has recorded it. Not usable in
`$filter` or `$orderby`.

  - `value.sizeInBytes` (integer)
    Size of the image file in bytes; `0` until processing has recorded it. Not usable in
`$filter` or `$orderby`.

  - `@readLink` (string)
    Canonical URL of this image — this request, echoed back. Present only when hypermedia enrichment
is enabled.

  - `@editLink` (string)
    URL to modify this image, identical to `@readLink`. Present only when hypermedia enrichment
is enabled.

## Response 401 fields (application/json):

  - `message` (string)
    Error description, e.g. `Unauthorized`.

  - `request_id` (string)
    Gateway request identifier, to quote when contacting support.

## Response 403 fields (application/json):

  - `message` (string)

  - `request_id` (string)

## Response 500 fields (application/json):

  - `error` (string)

  - `details` (any)