---
title: "Update an asset"
method: PATCH
path: "/websiteAssets/{assetId}"
tags: ["Assets"]
---

# Update an asset

`PATCH /websiteAssets/{assetId}`

## Request

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

Changes `filename`, `description`, or `category`. Pass only the fields to change; `null` clears a field. `category` is images only.

## Path parameters

- `assetId` string, required

## Request body

- object
  - `filename` string: Delivery URLs never change.
  - `description` string, nullable: One sentence: subject, visible text, style, intended use.
  - `category` 'logo' | 'icon' | 'photo' | 'illustration' | 'screenshot' | 'graphic' | 'background' | 'other', nullable: What the image is. Images only.

## Response `200`

The updated asset with its public CDN delivery URLs.

- object
  - `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`.
  - `originalUrl` string, required: Stable public CDN URL for the original bytes. It never expires.
  - `previewUrl` string, nullable, required: For SVG images, the stable public CDN URL of a rasterized PNG preview (longest edge 1024px) that image models, MCP previews, and favicon fallbacks use. `null` for other assets and for SVGs that could not be rendered.
  - `srcSet` string, nullable, required: Ready-to-use responsive image srcset. `null` when image transformation is unavailable.
  - `variants` object, required: Optimized image URLs keyed by pixel width. Empty when image transformation is unavailable.
  - `createdAt` string, date-time, required: When the upload was started.
  - `status` 'pending' | 'ready', required: `pending` until websiteAssets.finalize confirms the upload; `ready` once the asset is servable.

## 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)