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

# GET /v1/images/:type/:hash — Retrieve Stored Image

> Stream a stored image or 3D model file by type and hash identifier. Supports avatar, id card, full-body, 3D GLB model, and bank icon asset types.

Use this endpoint to retrieve binary image files stored on the CA Colombia platform. Images are identified by a `type` that describes the category of asset and a `hash` that is the unique identifier for a specific file. The server streams the image directly in the response body with appropriate `Content-Type` headers set.

Responses are aggressively cached — the server sets a one-year `Cache-Control` header (`public, max-age=31536000, immutable`) on every successful response. This means you can safely cache image URLs in your own application and expect them never to change for a given hash.

<Note>
  This endpoint does not require authentication. Images are publicly accessible by anyone who knows the correct `type` and `hash`.
</Note>

## Endpoint

```text theme={null}
GET /v1/images/:type/:hash
```

## Path Parameters

<ParamField path="type" type="string" required>
  The category of image to retrieve. Must be one of the following values:

  * `avatar-bust` — Character upper-body avatar image.
  * `ids` — In-game ID card images (e.g., national ID, driving licence).
  * `avatars3d` — 3D character avatar model files (returned as `model/gltf-binary` with a `.glb` extension).
  * `avatar` — Full-body character avatar image.
  * `icons` — Bank or organisation icon images.
</ParamField>

<ParamField path="hash" type="string" required>
  The file's unique hash identifier, including its file extension (e.g., `a3f2c1d4e5b6789012345678abcdef01.png`). Hash values are returned by other API endpoints — for example, `iconHash` on a bank object or the avatar hash on a user profile.
</ParamField>

## Response

A successful response streams the binary file directly in the response body.

| Header              | Value                                                                  |
| ------------------- | ---------------------------------------------------------------------- |
| `Content-Type`      | `image/png` for image files, `model/gltf-binary` for `.glb` 3D models. |
| `Cache-Control`     | `public, max-age=31536000, immutable`                                  |
| `CDN-Cache-Control` | `max-age=31536000`                                                     |

## Code Examples

<CodeGroup>
  ```javascript JavaScript (fetch) — display image in browser theme={null}
  const type = 'icons';
  const hash = 'a3f2c1d4e5b6789012345678abcdef01.png';

  const imageUrl = `https://api.cacolombia.com/v1/images/${type}/${hash}`;

  const img = document.createElement('img');
  img.src = imageUrl;
  document.body.appendChild(img);
  ```

  ```javascript JavaScript (fetch) — download as Blob theme={null}
  const type = 'ids';
  const hash = 'b9e4f2a1c3d5e67890123456789abcde.png';

  const res = await fetch(
    `https://api.cacolombia.com/v1/images/${type}/${hash}`
  );

  if (res.ok) {
    const blob = await res.blob();
    const objectUrl = URL.createObjectURL(blob);
    console.log('Image available at:', objectUrl);
  } else {
    console.error('Could not retrieve image:', res.status);
  }
  ```
</CodeGroup>

## Example Request

```text theme={null}
GET https://api.cacolombia.com/v1/images/icons/a3f2c1d4e5b6789012345678abcdef01.png
```

The response body is the raw PNG binary data. There is no JSON wrapper.

## Errors

| Status | Description                                                                                                        |
| ------ | ------------------------------------------------------------------------------------------------------------------ |
| `400`  | The `type` path parameter is not one of the allowed values (`avatar-bust`, `ids`, `avatars3d`, `avatar`, `icons`). |
| `404`  | No file was found for the given `type` and `hash` combination.                                                     |
| `500`  | The server encountered an error while retrieving the file from storage.                                            |

<Tip>
  Because responses include a long-lived `Cache-Control: immutable` header, you can use image URLs directly as `src` attributes in `<img>` tags or as background images in CSS. The browser and any CDN in front of the API will cache them efficiently without additional work on your part.
</Tip>