Skip to main content
GET
Search team assets for the agent

Authorizations

Authorization
string
header
required

A Melius API key (mel_...), sent as Authorization: Bearer <key>.

x-team-id
string
header
required

The team (workspace) to act on. Defaults to the key's team when omitted.

Query Parameters

query
string

The semantic search query — an exact filename or a description of the asset (e.g. "Product_Shot_05.png", "red logo", "the shark photo"). When the member gives an exact filename, pass it verbatim, including its extension; exact matches rank first. Provide a query to FIND specific assets. OMIT it entirely to bring in EVERY asset from a folder: when the member says "bring in all my assets from the X folder" / "add everything in X to the canvas", resolve the folder with list_asset_folders and call asset_search with just that folderId and NO query. Never invent a query when the member asked for everything in a folder — a query filters and will drop assets they wanted. Omitting the query requires a folderId.

Required string length: 1 - 500
limit
integer
default:20
Required range: 1 <= x <= 20
source
enum<string>

Optional. Filter by where the asset came from: upload for files uploaded by a member, or generated for media created in Melius. Set this only when the member explicitly asks for uploads or generations; omit it to search both.

Available options:
upload,
generated
fileType
enum<string>
Available options:
image,
video,
audio,
pdf,
text
canvasId
string<uuid>

Optional. Omit to search the whole team library — this is the default and what nearly every request wants (e.g. "use the asset I have"). Only set this to scope to a DIFFERENT canvas the member explicitly names ("search my other canvas"), resolving the id from canvas_list. Do NOT pass the canvas the chat is currently on (its assets are already visible via canvas_content, and scoping there hides whole-library matches), and never guess an id.

folderId
string<uuid>

Optional. Scope to one Files folder AND its subfolders. Omit to search the whole team library — the default, and what nearly every request wants. Set it when the member names a specific folder — either to FILTER within it (pass folderId + query, e.g. "find the shark shot in my ocean folder") or to bring in EVERYTHING in it (pass folderId and OMIT query, e.g. "add all my assets from the ocean folder"). Resolve the id with list_asset_folders: prefer a case-insensitive exact name or path before considering partial matches; if several exact or partial matches remain, ask which one. Never guess a folder id.

tags
string

Optional. Filter to assets carrying ALL of these tags (AND). Pass a tag name ONLY when the member explicitly asks to filter by a tag (e.g. "find my assets tagged brand", "my hero tag") — never infer one from ordinary words in their request. Comma-separated (e.g. "brand" or "brand,hero"), case-insensitive. Combine with query to search within tagged assets, or omit query (with tags and/or a folderId) to bring in every asset carrying them. An unknown or misspelled tag name matches nothing, so pass only tags the member actually named.

showInThread
boolean

Slack only. Set true when the member only wants to SEE the matched asset(s) — "find X and show it to me", "do I have Y?" — and is NOT asking to place, edit, or build on them. Skips the selection card and posts every match straight into the Slack thread as image files. Leave unset (the default) whenever the member wants to USE an asset on the canvas, so the selection card renders and a canvas gets bound.

mode
enum<string>
Available options:
semantic,
filename
offset
integer
Required range: x >= 0

Response

200

query
string
required
results
object[]
required
total
integer
required
Required range: x >= 0
folderId
string<uuid>
canvasId
string<uuid>
source
enum<string>
Available options:
upload,
generated
fileType
enum<string>
Available options:
image,
video,
audio,
pdf,
text
tags
string
Last modified on August 24, 2026