Tools: images

These tools manage the site's image library. Every image on the site must come from the library; see Images in code. Supported formats are JPEG, PNG, WebP, GIF and SVG, up to 20 MB per file. AVIF isn't supported.

browse_assets

Lists the images in the site's library with each image's ID, name, URL, size, alt text, file type and tags.

When to use it: Before placing an image, to use one that's already there.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "success": true,
  "assets": [
    {
      "id": "storefront-k2j9",
      "name": "Storefront",
      "url": "/_images/storefront~4f1c9a/public",
      "width": 1920,
      "height": 1280,
      "alt": "Bakery storefront at dawn",
      "mimeType": "image/jpeg",
      "source": "upload",
      "tags": [
        "storefront",
        "exterior"
      ]
    }
  ]
}

Use url exactly as given in <img src>. id is the library ID that modify_asset takes. The image ID that assets_usage and assets_apply_alt take is the part of url between ~ and the next / (4f1c9a above).

view_asset

Returns the image itself so your AI can look at it.

When to use it: To check what an image shows, especially before writing alt text.

Needs an open turn: No.

Input	Type	Required	Meaning
url	string	Yes	The image URL from browse_assets or import_asset.
size	string: thumbnail, small, medium or full	No	thumbnail is a 200×200 crop; small, medium and full show the whole image at 640 px, 1024 px or original width. Default medium.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "url": "/_images/storefront~4f1c9a/public",
  "size": "small"
}

Example result

The image, plus {"ok": true, "size": "small"}.

Errors

You see	What it means	What to do
invalid_url	That isn't an image URL from the library.	Use the URL from browse_assets.
fetch_failed	The image couldn't be loaded.	Check the URL and retry.

import_asset

Copies an image from a public web address into the library and returns its URL. The result includes a small preview so your AI can check the image and write accurate alt text.

When to use it: When the image is already online. For a file on the user's computer, use request_asset_upload.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
url	string	Yes	The image's web address.
alt	string	No	Alt text describing what the image shows. Base it on the image, not the file name.
tags	array of strings	No	Lowercase tags, such as ["team", "office"].

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "url": "https://example.com/photos/storefront.jpg",
  "alt": "Bakery storefront at dawn",
  "tags": [
    "storefront"
  ]
}

Example result

{
  "success": true,
  "asset": {
    "id": "storefront-k2j9",
    "name": "Storefront",
    "url": "/_images/storefront~4f1c9a/public",
    "width": 1920,
    "height": 1280
  }
}

Errors

You see	What it means	What to do
"Unsupported image type: …"	The file isn't JPEG, PNG, WebP, GIF or SVG.	Use another image.
Download failed	The address couldn't be fetched.	Check that the address is public and points to an image.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

request_asset_upload

Gives your AI a short-lived upload link for adding an image file from the user's computer. Your AI then uploads the file from its own terminal.

When to use it: When the user has an image file on disk, such as a logo. Only works in AI apps that can run shell commands, such as Claude Code and Codex.

Needs an open turn: Yes. Call start_turn first.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "success": true,
  "upload_url": "https://app.starjay.com/…",
  "token": "…",
  "expires_at": "2026-10-17T22:10:00.000Z",
  "max_bytes": 20971520
}

Upload the file with one request, using the returned values:

curl -X POST "<upload_url>" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/logo.png" \
  -F "alt=Bakery logo"

The response is the new library image. The link works for 10 minutes, only for this site, and only while your agent's turn is open. If it expires, ask for a new one. Upload errors you might see: "File too large", "Unsupported image type", "File content does not match a supported image format", and site_upload_rate_exceeded (wait a while before uploading more).

Errors

You see	What it means	What to do
"Could not mint an upload token right now."	Starjay couldn't create the link.	Retry in a moment.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

modify_asset

Renames an image in the library or replaces its tags. The image's URL never changes.

When to use it: To tidy up the library. For alt text, use assets_apply_alt.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
action	string: rename or tags	Yes	What to change.
id	string	Yes	The image's library id from browse_assets (not its URL).
name	string	For rename	The new display name, up to 200 characters.
tags	array of strings	For tags	The complete new tag list. It replaces the old one.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "action": "tags",
  "id": "storefront-k2j9",
  "tags": [
    "storefront",
    "exterior",
    "morning"
  ]
}

Example result

{
  "success": true
}

Errors

You see	What it means	What to do
Image not found	No library image has that id.	Use the id from browse_assets.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

assets_usage

Shows where images are used: in the site's code (file, line and snippet) and in CMS items.

When to use it: Before replacing or asking the user to delete an image. With assetId it checks one image, which is much faster.

Needs an open turn: No.

Input	Type	Required	Meaning
assetId	string	No	The image ID (the part of the URL between ~ and the next /). Leave out for every image.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "assetId": "4f1c9a"
}

Example result

{
  "locations": [
    {
      "file": "src/components/sections/Hero.astro",
      "line": 12,
      "snippet": "<img src=\"/_images/storefront~4f1c9a/public\" …"
    }
  ],
  "cmsItems": []
}

If the result has cmsUsageError: true, the CMS couldn't be checked. Don't assume the image is unused.

assets_apply_alt

Changes alt text everywhere an image is placed with a particular alt text. Placements with different, hand-written alt text are left alone.

When to use it: After renaming or re-describing an image, to update its default alt text across the site.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
assetId	string	Yes	The image ID (the part of the URL between ~ and the next /).
matchAlt	string	Yes	Only placements whose current alt text is exactly this are changed.
newAlt	string	Yes	The new alt text.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "assetId": "4f1c9a",
  "matchAlt": "Storefront",
  "newAlt": "Bakery storefront at dawn"
}

Example result

{
  "success": true,
  "updated": 2
}

Errors

You see	What it means	What to do
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

Related

• The image library
• Alt text and descriptions