---
title: "List or search assets"
method: GET
path: "/websiteAssets"
tags: ["Assets"]
---

# List or search assets

`GET /websiteAssets`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/websiteAssets`
- Auth: HTTP bearer

Returns ready assets newest first as compact rows (`description`, `category`, dimensions, `url`, `srcSet`); fetch one asset for `originalUrl` and `variants`. Filter by `kind`, `category`, `type` (the broad MIME family: image, video, audio, font, or document), or `search`, which prefix-matches each term against the filename, description, and category; every term must match, else any term. Page size defaults to 50 (max 100).

## Query parameters

- `websiteId` string, required
- `kind` 'image' | 'file'
- `category` 'logo' | 'icon' | 'photo' | 'illustration' | 'screenshot' | 'graphic' | 'background' | 'other': Only images with this category.
- `type` 'image' | 'video' | 'audio' | 'font' | 'document': Broad file type derived from the MIME type: image, video, audio, font, or document (everything else). Combines with kind, category, and search.
- `search` string: Matches filename, description, and category; each term matches as a prefix.
- `cursor` string
- `limit` integer

## Response `200`

One page of ready assets, newest first.

- object
  - `items` object[], required
    - `id` string, required: Unique asset id. Pass it to websiteAssets.get and websiteAssets.delete.
    - `kind` 'image' | 'file', required: Asset kind. Each kind has its own MIME allowlist and size limit.
    - `filename` string, required: Original filename supplied at upload (1–255 characters).
    - `mimeType` string, required: MIME type stored for the asset after upload normalization.
    - `description` string, nullable, required: One-line description supplied at upload, edited later, or generated for dashboard uploads. `null` when absent.
    - `category` 'logo' | 'icon' | 'photo' | 'illustration' | 'screenshot' | 'graphic' | 'background' | 'other', nullable, required: Image category: logo, icon, photo, illustration, screenshot, graphic, background, or other. `null` for files and unclassified images.
    - `byteSize` integer, required: Exact file size in bytes.
    - `width` integer, nullable, required: Intrinsic pixel width, recorded at finalize for images. `null` for non-images and formats whose dimensions cannot be read.
    - `height` integer, nullable, required: Intrinsic pixel height; see `width`.
    - `colors` object[], nullable, required: Up to 8 representative colors sorted by share. `null` for files and for images that could not be analyzed.
      - `hex` string, required: Uppercase sRGB hex, exact for flat colors.
      - `share` number, nullable, required: Fraction of opaque pixels this color and its anti-aliasing cover. `null` for SVG, whose colors are read from the source instead of rendered.
      - `accent` boolean, required: Saturated enough to matter as an accent even at a small share.
    - `transparentShare` number, nullable, required: Fraction of the backdrop that shows through, weighting each pixel by its transparency: 0 for an opaque image, roughly the background area for a cutout, 0.5 for a uniform 50% overlay. `null` when unknown.
    - `translucentShare` number, nullable, required: Fraction of pixels with partial alpha (soft shadows, glows, fades, glass), excluding fully transparent and fully opaque pixels. `null` when unknown.
    - `sourceAssetId` string, nullable, required: For a background-removed image, the id of the asset it was derived from.
    - `url` string, required: Optimized public CDN URL for display. Transformable images use the 1920px default variant; other assets use `originalUrl`.
    - `srcSet` string, nullable, required: Ready-to-use responsive image srcset. `null` when image transformation is unavailable.
    - `createdAt` string, date-time, required: When the upload was started.
  - `nextCursor` string, nullable, required: Opaque cursor for the next page. Pass it as the `cursor` parameter on the next request. `null` when this is the last page.

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

[API](https://skmtc.dev/cactal/apis/cactal-api.md) · [All operations](https://skmtc.dev/cactal/apis/cactal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cactal/apis/cactal-api/revisions/9cd0fb5eacdd?raw)