> ## 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.
# List images
> List the site's Media Library images with alt text, AI metadata, and article links
Returns the site's Media Library images, newest first. This covers every source — AI-generated (`ai`), uploaded (`upload`), OEM stock (`oem`), reference images (`reference`), and social-platform cuts (`social_variant`).
Each row is a full [Image](/api-reference/images/get-image) minus `variants`; call **Get image** for a specific asset when you need its social variant sizes.
In-flight and failed AI generations are placeholder rows and are hidden by default. Pass `status=generating` or `status=error` to see them.
**Scope required:** `images:read`
## Query parameters
One of `ai`, `upload`, `oem`, `reference`, `social_variant`. Omit for all.
One of `generating`, `complete`, `error`. Omit for finished images only.
Only images attached to this content item (UUID).
Only images carrying this tag.
Substring match on alt text, title, and description.
Page size, 1–100.
Opaque cursor from a previous page's `pagination.next_cursor`.
## Example
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.app.hrizn.io/v1/public/images?source=ai&tag=rav4&limit=10" \
-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&tag=rav4&limit=10",
{ 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", "tag": "rav4", "limit": 10},
)
images = response.json()["data"]
```
```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"data": [
{
"image_id": "2c9c5b1e-6d0d-4c74-9c8f-3b1e0a5d8f21",
"generation_id": "7a3f2e10-1b2c-4d5e-8f90-abcdef123456",
"status": "complete",
"image_url": "https://assets.app.hrizn.io/public/media-library/8f1c.../7a3f2e10.jpg",
"error": null,
"source": "ai",
"alt_text": "Red Toyota RAV4 Hybrid parked outside a dealership at sunset",
"title": "Red RAV4 Hybrid at Sunset",
"caption": "A red RAV4 Hybrid in front of a modern dealership at golden hour.",
"description": "Representative render of a red RAV4 Hybrid for a landing page hero.",
"tags": ["ai", "rav4"],
"width": 1376,
"height": 768,
"aspect_ratio": "16:9",
"created_at": "2026-09-06T14:28:00.000Z",
"updated_at": "2026-09-06T14:28:31.000Z",
"generated_at": "2026-09-06T14:28:27.609Z",
"generation": {
"prompt": "A red Toyota RAV4 hybrid parked in front of a modern dealership at golden hour",
"generation_prompt": "Photorealistic red Toyota RAV4 Hybrid, three-quarter front view, ...",
"disclaimer": "Representative image. Actual vehicle may vary."
},
"article_id": null,
"parent_image_id": null,
"variants": []
}
],
"pagination": {
"has_more": false,
"next_cursor": null,
"total_count": 1
}
}
```
## OpenAPI
````yaml GET /images
openapi: 3.1.0
info:
title: Hrizn Public API
version: 1.2.0
description: >
The Hrizn Public API allows partners to programmatically create content,
manage inventory descriptions, and integrate with the Hrizn platform.
All endpoints are prefixed with `/public` and require an API key passed via
the `X-API-Key` header (except the health check).
contact:
email: support@hrizn.io
servers:
- url: https://api.app.hrizn.io/v1/public
description: Production
security:
- apiKeyAuth: []
tags:
- name: Analytics
description: >-
Warehoused Google Search Console and GA4 reads (Teams+ API access,
analytics:read). URL Inspection is live only on pages/performance.
- name: IdeaClouds
description: Create and manage AI-powered keyword research
- name: Content Intelligence
description: AI-powered content gap analysis and recommendations
- name: Content
description: Generate content from IdeaClouds
- name: Compliance
description: Run OEM compliance checks on content
- name: Content Tools
description: Generate SEO metadata, schemas, and social snippets
- name: Inventory
description: Access vehicle data and AI descriptions
- name: Images
description: >-
Media Library images. Read the library (images:read): list and fetch
images with alt text, AI-written title/caption/description, the generating
prompt, dimensions, article links, and social variant cuts. Generate
(images:write): async AI image generation returning an image_id;
completion is delivered via image.generation.completed /
image.generation.failed webhooks.
- name: Market
description: >-
Live local market listings, days supply, competitive set, and pricing
insights (Unlimited plan + market_data:read)
- name: Site
description: View dealership details and configuration
- name: Webhooks
description: Manage webhook subscriptions for real-time events
- name: Reference
description: Look up available types, scopes, and events
- name: Social
description: >-
Social Hub posting and reviews across all connected platforms (X,
Facebook, Instagram, LinkedIn, Google Business Profile)
- name: Health
description: Health check (no authentication)
paths:
/images:
get:
tags:
- Images
summary: List images
description: >-
List the site's Media Library images, newest first. Covers AI-generated,
uploaded, OEM, reference, and social-variant assets. Each row is a full
Image (alt text, AI metadata, prompts, dimensions, article link) but
without variants — call GET /images/{imageId} for those. In-flight and
failed AI generations are hidden unless status=generating or
status=error is passed. Requires images:read.
operationId: listImages
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
- name: source
in: query
schema:
type: string
enum:
- ai
- upload
- oem
- reference
- social_variant
description: Restrict to one asset source.
- name: status
in: query
schema:
type: string
enum:
- generating
- complete
- error
description: >-
Generation status. Omit for finished images; generating or error
surfaces placeholder rows for in-flight or failed AI generations.
- name: article_id
in: query
schema:
type: string
format: uuid
description: Only images attached to this content item.
- name: tag
in: query
schema:
type: string
description: Only images carrying this tag.
- name: query
in: query
schema:
type: string
description: Substring match on alt text, title, and description.
responses:
'200':
description: Paginated list of images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
Limit:
name: limit
in: query
schema:
type: integer
default: 25
minimum: 1
maximum: 100
description: Number of results per page
Cursor:
name: cursor
in: query
schema:
type: string
description: Base64-encoded pagination cursor
schemas:
ImageListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Image'
pagination:
$ref: '#/components/schemas/PaginationInfo'
Image:
type: object
description: >-
A Media Library image. The first five fields form the async-generation
poll contract and are always present; the rest describe the finished
asset.
properties:
image_id:
type: string
format: uuid
generation_id:
type: string
format: uuid
nullable: true
status:
type: string
enum:
- generating
- complete
- error
image_url:
type: string
nullable: true
description: Public asset URL once status is complete.
error:
type: string
nullable: true
source:
type: string
nullable: true
enum:
- ai
- upload
- oem
- reference
- social_variant
alt_text:
type: string
nullable: true
description: >-
Accessibility text. AI images receive an AI-written value after
generation.
title:
type: string
nullable: true
caption:
type: string
nullable: true
description:
type: string
nullable: true
tags:
type: array
items:
type: string
width:
type: integer
nullable: true
height:
type: integer
nullable: true
aspect_ratio:
type: string
nullable: true
example: '16:9'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
nullable: true
generated_at:
type: string
format: date-time
nullable: true
description: When the AI render finished (AI images only).
generation:
type: object
nullable: true
description: Present for AI-generated images.
properties:
prompt:
type: string
nullable: true
description: The creative prompt supplied by the caller.
generation_prompt:
type: string
nullable: true
description: The expanded prompt Hrizn sent to the model.
disclaimer:
type: string
nullable: true
description: E-E-A-T disclaimer to display alongside the image.
article_id:
type: string
format: uuid
nullable: true
description: Content item this image is attached to, if any.
parent_image_id:
type: string
format: uuid
nullable: true
description: Set when this image is itself a social variant of another image.
variants:
type: array
description: Social variant cuts of this image. Empty on list rows.
items:
$ref: '#/components/schemas/ImageVariant'
PaginationInfo:
type: object
properties:
has_more:
type: boolean
next_cursor:
type: string
nullable: true
total_count:
type: integer
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: validation_error
message:
type: string
example: 'keyword: Required'
details:
type: object
request_id:
type: string
ImageVariant:
type: object
description: A social-platform cut generated from a parent image.
properties:
image_id:
type: string
format: uuid
description: The variant's own Media Library asset id.
preset_key:
type: string
description: >-
Social preset key (igFeedSquare, igFeedPortrait, story, xLandscape,
linkedinWide).
preset_label:
type: string
nullable: true
width:
type: integer
nullable: true
height:
type: integer
nullable: true
aspect_ratio:
type: string
nullable: true
example: '1:1'
image_url:
type: string
nullable: true
status:
type: string
enum:
- generating
- complete
- error
responses:
BadRequest:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: API key lacks required scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
RateLimited:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Hrizn API key (prefix hzk_)
````