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

# images:read

> List and view Media Library images, alt text, prompts, and social variants

<code>images:read</code>

The `images:read` scope lets you browse a site's Media Library and read everything Hrizn knows about an image: its public URL, alt text, AI-written title / caption / description, tags, dimensions, the prompt that generated it, the E-E-A-T disclaimer, the content item it is attached to, and every social-platform cut derived from it. It is included in the **Full Access**, **Read Only**, and **Content Generation** presets and in every MCP profile.

Reads are not plan-gated. Placeholder rows for in-flight or failed AI generations are hidden from the list unless you ask for them by `status`.

## Endpoints

| Method | Path                       | Description                                                           |
| ------ | -------------------------- | --------------------------------------------------------------------- |
| `GET`  | `/public/images`           | List images (paginated, filterable)                                   |
| `GET`  | `/public/images/{imageId}` | Read one image with variants; also the async-generation poll endpoint |

***

## List images

```
GET /public/images
```

Newest first, across all sources (`ai`, `upload`, `oem`, `reference`, `social_variant`). Filter with `source`, `status`, `article_id`, `tag`, or `query`. List rows omit `variants` — fetch a single image for those.

### Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.app.hrizn.io/v1/public/images?source=ai&article_id=9d2e1f30-4b5c-4d6e-8f70-1234567890ab" \
    -H "X-API-Key: hzk_your_key_here"
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.app.hrizn.io/v1/public/images?source=ai&article_id=9d2e1f30-4b5c-4d6e-8f70-1234567890ab",
    { headers: { "X-API-Key": "hzk_your_key_here" } },
  );
  const { data, pagination } = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.app.hrizn.io/v1/public/images",
      headers={"X-API-Key": "hzk_your_key_here"},
      params={"source": "ai", "article_id": "9d2e1f30-4b5c-4d6e-8f70-1234567890ab"},
  )
  images = response.json()["data"]
  ```
</CodeGroup>

***

## Get image

```
GET /public/images/{imageId}
```

Full detail for one image including `variants[]`. When the image is still generating, `status` is `generating` and `image_url` is `null`; the completed / failed transition is also delivered via the `image.generation.*` [webhooks](/webhooks).

### Using the response

* Put `alt_text` on the `<img>` — for AI images it is rewritten by Hrizn's alt-text pass shortly after generation.
* Show `generation.disclaimer` near any AI-generated vehicle image.
* Pick a `variants[]` entry by `preset_key` when posting to a specific social platform instead of re-cropping `image_url` yourself.

***

## Related

* [`images:write`](/scopes/images-write) — start or regenerate AI images.
* [Webhooks](/webhooks) — `image.generation.completed` and `image.generation.failed`.