---
title: "Import assets from public URLs"
method: POST
path: "/websiteAssets/import"
tags: ["Assets"]
---

# Import assets from public URLs

`POST /websiteAssets/import`

## Request

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

Fetches 1-10 public http(s) URLs server-side, one at a time, and stores each as a ready asset with no upload or finalize step. Media only: images, fonts, PDF, audio, video, dotLottie, and Rive; text, data, documents, and archives are refused. Images, fonts, and PDFs must parse as what they claim, hosts on private addresses are rejected, the upload kind and MIME rules apply, and each download is capped at 30 MiB (larger files must be uploaded directly). Each item may carry a `description` and, for images, a `category`. Name each item by `url`, or by `photo`: the number over a picture on contact sheets `webResearch.profile` or `webResearch.viewImage` showed you, which saves copying its long signed link. `assets` carries successes with CDN URLs and `sourceUrl`; `errors` carries failures typed `invalid_url`, `non_public_address`, `unreachable`, `too_large`, `unsupported_type`, `signature_expired`, or `unknown_photo` (a number you were not shown or that expired; look at the pictures again for current numbers). Import only assets you have the right to use.

## Request body

- object
  - `websiteId` string, required
  - `items` object[], required: Each item succeeds or fails on its own.
    - `url` string, uri: Public http(s) URL of the file to import.
    - `filename` string: Stored filename; defaults to the URL path segment.
    - `description` string: One sentence: subject, visible text, style, intended use.
    - `category` 'logo' | 'icon' | 'photo' | 'illustration' | 'screenshot' | 'graphic' | 'background' | 'other': What the image is. Images only.
    - `photo` integer: Instead of `url`: the number over a picture on contact sheets `webResearch.profile` or `webResearch.viewImage` showed you.

## Response `200`

Imported assets with CDN delivery URLs, plus per-URL failures.

- object
  - `assets` object[], required: Ready assets.
    - `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.
    - `sourceUrl` string, required: The imported URL.
    - `photo` integer: The photo number it was named by.
  - `errors` object[], required: Failed items.
    - `url` string
    - `photo` integer
    - `type` 'invalid_url' | 'non_public_address' | 'unreachable' | 'too_large' | 'unsupported_type' | 'signature_expired' | 'unknown_photo', required
    - `message` string, required

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