Asset tools

Tools for browsing, retrieving, and generating assets (images, videos, audio) in the organization's asset library.

get-assets

Search and retrieve assets from the library with optional filters.

Use search for natural-language queries

This tool supports server-side natural-language search — pass what the user asked for (e.g. "images of old people", "beach sunset", "hotel lobby at night") directly into the search parameter. It runs a semantic search over each asset's AI-generated visual description, name, and tags. Don't call get-assets without search and then manually scan the returned visualDescription fields yourself — the server-side search is more accurate and avoids paging through the entire library.

Parameters

Parameter	Type	Required	Description
`search`	`string`	No	Natural-language search query, e.g. `"images of old people"`. Matches semantically against name, visual description, and tags — pass user phrasing straight through instead of filtering results yourself
`collectionId`	`string`	No	Filter by collection ID
`tags`	`string`	No	Comma-separated tag IDs (use `get-tags` to get IDs)
`uncategorized`	`boolean`	No	Only return assets without a collection
`assetType`	`string`	No	Filter by type: `image`, `audio`, or `video`
`insertProductId`	`string`	No	Filter by associated product ID
`limit`	`number`	No	Page size, 1–200 (default `50`, newest first)
`offset`	`number`	No	Number of assets to skip for pagination (default `0`)

Ordering with search

When search is provided, results are ranked by relevance (best match first) instead of newest first.

Response

Field	Type	Description
`assets`	`array`	List of assets (this page)
`assets[].id`	`string`	Unique asset identifier
`assets[].name`	`string`	Asset name
`assets[].assetUrl`	`string \| null`	Full-resolution URL
`assets[].previewUrl`	`string \| null`	Preview/thumbnail URL
`assets[].status`	`string`	Processing status
`assets[].visualDescription`	`string \| null`	AI-generated description
`assets[].assetType`	`string`	`image`, `audio`, or `video`
`assets[].collection`	`object \| null`	`{ name }` if assigned
`assets[].insertProducts`	`array`	`[{ name }]`, linked products
`assets[].tags`	`array`	`[{ name }]`, assigned tags
`assets[].createdAt`	`string`	ISO date
`assets[].updatedAt`	`string`	ISO date
`returned`	`number`	Number of assets in this page
`limit`	`number`	Page size used
`offset`	`number`	Offset used
`hasMore`	`boolean`	`true` if the page was full; call again with `offset += limit`

Pagination

Large libraries are paged to keep responses fast. When hasMore is true, request the next page by increasing offset by limit (e.g. offset: 50, then 100, …).

Example

{
  "tool": "get-assets",
  "arguments": {
    "search": "images of old people",
    "assetType": "image"
  }
}

get-asset

Retrieve a single asset by ID with full metadata, tags, and custom field values.

Each entry in customFields covers one org-defined field: display is human-readable (option labels resolved), value is the write shape to pass back into update-asset. Discover the field catalog with get-asset-fields before editing.

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Asset identifier

Response

Field	Type	Description
`asset.id`	`string`	Unique identifier
`asset.name`	`string`	Asset name
`asset.assetUrl`	`string \| null`	Full-resolution URL
`asset.previewUrl`	`string \| null`	Preview URL
`asset.status`	`string`	Processing status
`asset.visualDescription`	`string \| null`	AI-generated description
`asset.assetType`	`string`	`image`, `audio`, or `video`
`asset.collection`	`object \| null`	`{ id, name }`
`asset.tags`	`array`	`[{ id, name, colorScheme }]`
`asset.customFields`	`array`	All org fields with current values (see below)
`asset.customFields[].fieldId`	`string`	Field definition UUID (key for writes)
`asset.customFields[].label`	`string`	Human field name
`asset.customFields[].type`	`string`	`text` / `number` / `boolean` / `date` / `select` / `multiselect`
`asset.customFields[].required`	`boolean`	Whether the org treats the field as required
`asset.customFields[].value`	`object \| null`	Raw write shape, or `null` if unset
`asset.customFields[].display`	`string \| null`	Human-readable value (labels resolved)
`asset.createdAt`	`string`	ISO date
`asset.updatedAt`	`string`	ISO date

Example

{
  "tool": "get-asset",
  "arguments": {
    "id": "ast_xyz789"
  }
}

get-asset-fields

List the organization's custom asset field definitions (metadata schema). Call this before reading or writing custom metadata so you have field ids, types, and select option UUIDs.

Workflow

get-asset-fields — discover schema
get-asset — see current values (optional)
update-asset with customFields keyed by field id

Value shapes

Field type	Write value
`text`	`{ "type": "text", "value": "…" }`
`number`	`{ "type": "number", "value": 42 }`
`boolean`	`{ "type": "boolean", "value": true }`
`date`	`{ "type": "date", "value": "YYYY-MM-DD" }`
`select`	`{ "type": "select", "optionId": "<options[].id>" }` — never the label
`multiselect`	`{ "type": "multiselect", "optionIds": ["<uuid>", …] }` — never labels

Pass null for a field id to clear it. Omitted keys stay unchanged (merge).

Definition admin

This tool only lists definitions. Creating or editing fields/options remains in the heycreo settings UI / REST API.

Parameters

None.

Response

Field	Type	Description
`fields`	`array`	Field definitions
`fields[].id`	`string`	Field UUID — key in `update-asset.customFields`
`fields[].label`	`string`	Display name (e.g. `Kampagne`)
`fields[].type`	`string`	Value type (must match write `"type"`)
`fields[].required`	`boolean`	Treated as required by the org
`fields[].options`	`array`	For select/multiselect: `[{ id, label }]`
`fields[].writeHint`	`string`	How to set this field
`fields[].exampleValue`	`object`	Copy-paste example for `customFields[id]`
`total`	`number`	Number of fields
`howToWrite`	`string`	Short workflow reminder

Example

{
  "tool": "get-asset-fields",
  "arguments": {}
}

update-asset

Update asset metadata: name, descriptions, folder, tags, and/or custom fields.

Parameters

Parameter	Type	Required	Description
`assetId`	`string`	Yes	Asset id
`name`	`string`	No	Display name
`description`	`string`	No	Description
`visualDescription`	`string`	No	Editable visual description (feeds semantic search)
`altText`	`string \| null`	No	Alt text; empty/`null` resets to asset name
`collectionId`	`string \| null`	No	Folder UUID, or `null` for library root
`tagIds`	`string[]`	No	Replaces all tags (full desired list; `[]` clears). Use `get-tags` / `create-tag`
`customFields`	`object`	No	Map of `fieldId` → value or `null` (see get-asset-fields)

Example — set a select custom field

{
  "tool": "update-asset",
  "arguments": {
    "assetId": "ast_xyz789",
    "customFields": {
      "f-campaign-uuid": {
        "type": "select",
        "optionId": "opt-summer-uuid"
      }
    }
  }
}

get-tags

List all tags for the organization, including how many assets each tag has.

Parameters

None.

Response

Field	Type	Description
`tags`	`array`	List of tags
`tags[].id`	`string`	Tag identifier
`tags[].name`	`string`	Tag name
`tags[].colorScheme`	`string`	Display color
`tags[].assetCount`	`number`	Number of assets with this tag
`tags[].createdAt`	`string`	ISO date
`tags[].updatedAt`	`string`	ISO date
`total`	`number`	Total number of tags

generate-asset

Generate a new image using AI. The generated asset is added to the organization's asset library.

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Yes	Description of the image to generate
`mode`	`string`	No	Generation mode: `stock` (generic), `product` (product-focused), or `productContent`
`productImageType`	`string`	No	For product modes: `packaging` or `content`
`insertProductIds`	`string[]`	No	Up to 3 product IDs to use as reference (for product modes)

Response

Field	Type	Description
`asset.id`	`string`	ID of the generated asset
`asset.name`	`string`	Auto-generated name
`asset.prompt`	`string`	The prompt used
`asset.status`	`string`	Processing status (may be `processing` initially)
`asset.assetType`	`string`	Always `image`
`asset.createdAt`	`string`	ISO date
`asset.updatedAt`	`string`	ISO date
`message`	`string`	Status message

Example

{
  "tool": "generate-asset",
  "arguments": {
    "prompt": "A modern office workspace with a laptop and coffee, warm lighting, professional photography style",
    "mode": "stock"
  }
}

upload-asset

Upload a small image into the organization's asset library so it can be inserted into a design. Provide either a publicly fetchable imageUrl (the server downloads it) or inline base64 data with a mimeType. By default the asset is not filed into any collection (it stays in the library root); pass an optional collectionId to place it in a specific collection. The upload returns a persistent assetUrl.

Supported formats: jpeg, png, gif, webp, svg. Both base64 and imageUrl are capped at 12 MB. For larger files, local Cowork folders, or bulk imports, use begin-asset-upload instead (bytes never go through the LLM).

Parameters

Parameter	Type	Required	Description
`imageUrl`	`string`	One of `imageUrl`/`base64`	Direct URL the server downloads and stores (max 12 MB)
`base64`	`string`	One of `imageUrl`/`base64`	Base64-encoded image bytes (a `data:` prefix is accepted; max 12 MB decoded)
`mimeType`	`string`	No	MIME type for base64 data, e.g. `image/png` (default `image/png`)
`name`	`string`	No	Descriptive asset name, e.g. `hero-mountains`
`collectionId`	`string`	No	Existing collection id to file the asset into. Omit to leave it in the library root. Use `get-collections` to discover ids or `create-collection` to make a new one

Response

Field	Type	Description
`ok`	`boolean`	`true` on success
`asset.id`	`string`	New asset ID
`asset.name`	`string`	Stored asset name
`asset.assetUrl`	`string \| null`	Persistent URL; use this to insert the image
`asset.previewUrl`	`string \| null`	Preview URL
`asset.assetType`	`string`	Always `image`
`asset.status`	`string`	Processing status
`note`	`string`	Hint on how to place it in the editor

On failure the tool returns an error string (e.g. unfetchable URL, unsupported type, too large).

Example

{
  "tool": "upload-asset",
  "arguments": {
    "imageUrl": "https://example.com/photo.jpg",
    "name": "campaign-hero"
  }
}

Insert it into a design

After uploading, place the image in a Studio document with studio_call (target it with templateId or designId):

{
  "tool": "studio_call",
  "arguments": {
    "templateId": "<template id>",
    "tool": "studio_create_image",
    "args": { "source": "custom", "customUrl": "<assetUrl from upload-asset>", "name": "campaign-hero" }
  }
}

begin-asset-upload

Start an out-of-band image upload for large or local files (Claude Cowork folders, multi‑MB originals, bulk imports). Returns a one-time uploadUrl + ticket. The client uploads binary bytes with HTTP multipart — not through the MCP tool JSON:

curl -X POST \
  -F "file=@/path/to/image.jpg" \
  -F "ticket=<ticket from begin-asset-upload>" \
  "<uploadUrl>"

Typical Cowork workflow:

create-collection for the folder (optional)
Per file: begin-asset-upload → curl multipart → read asset.id from the HTTP response
Optionally create-product with assetId to attach the image to a catalog entry

Supported formats: jpeg, png, gif, webp, svg. Max 100 MB per file. Tickets expire in 15 minutes and are single-use.

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Asset filename stem, e.g. `hero-mountains`
`mimeType`	`string`	Yes	MIME type of the file you will upload, e.g. `image/jpeg`
`collectionId`	`string`	No	Collection to file the asset into
`byteSize`	`number`	No	Expected size in bytes (early rejection if over the limit)

Response

Field	Type	Description
`ok`	`boolean`	`true` on success
`uploadUrl`	`string`	`POST` target for multipart upload
`ticket`	`string`	One-time ticket (multipart field `ticket` or header `X-heycreo-Upload-Ticket`)
`expiresAt`	`string`	ISO expiry
`maxBytes`	`number`	Max accepted file size
`curlExample`	`string`	Ready-to-run curl snippet

The multipart redeem endpoint returns the same asset shape as upload-asset.

get-assets​

Parameters​

Response​

Example​

get-asset​

Parameters​

Response​

Example​

get-asset-fields​

Workflow​

Value shapes​

Parameters​

Response​

Example​

update-asset​

Parameters​

Example — set a select custom field​

get-tags​

Parameters​

Response​

generate-asset​

Parameters​

Response​

Example​

upload-asset​

Parameters​

Response​

Example​

begin-asset-upload​

Parameters​

Response​

get-assets

Parameters

Response

Example

get-asset

Parameters

Response

Example

get-asset-fields

Workflow

Value shapes

Parameters

Response

Example

update-asset

Parameters

Example — set a select custom field

get-tags

Parameters

Response

generate-asset

Parameters

Response

Example

upload-asset

Parameters

Response

Example

begin-asset-upload

Parameters

Response