> ## Documentation Index > Fetch the complete documentation index at: https://docs.melius.com/llms.txt > Use this file to discover all available pages before exploring further. # Search team assets for the agent ## OpenAPI ````yaml /api/openapi.json get /api/v1/files/agent-search openapi: 3.0.2 info: title: Melius API version: '1' description: >- The Melius REST API. Authenticate with an API key as a bearer token (`Authorization: Bearer mel_...`) and select the team to act on with the `x-team-id` header. Generations run through the same node + run pipeline as the app: create a node on a canvas, start a run, poll the run, then read the resulting version asset. servers: - url: https://api.melius.com security: - apiKey: [] teamId: [] paths: /api/v1/files/agent-search: get: tags: - asset summary: Search team assets for the agent operationId: asset.search parameters: - name: query in: query schema: type: string minLength: 1 maxLength: 500 description: >- 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`. description: >- 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`. - name: limit in: query schema: default: 20 type: integer minimum: 1 maximum: 20 - name: source in: query schema: type: string enum: - upload - generated description: >- 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. description: >- 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. - name: fileType in: query schema: type: string enum: - image - video - audio - pdf - text - name: canvasId in: query schema: type: string format: uuid description: >- 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. description: >- 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. - name: folderId in: query schema: type: string format: uuid description: >- 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. description: >- 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. - name: tags in: query schema: type: string description: >- 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. description: >- 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. - name: showInThread in: query schema: type: boolean description: >- 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. description: >- 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. - name: mode in: query schema: type: string enum: - semantic - filename - name: offset in: query schema: type: integer minimum: 0 responses: '200': description: '200' content: application/json: schema: type: object properties: query: type: string results: type: array items: type: object properties: assetId: type: string format: uuid folderId: type: string format: uuid nullable: true filename: type: string displayName: type: string source: type: string enum: - upload - generated fileType: type: string enum: - image - video - audio - pdf - text contentType: type: string nullable: true fileSizeInKb: type: integer nullable: true durationInMs: type: integer nullable: true previewUrl: type: string nullable: true assetUrl: type: string nullable: true createdAt: type: string format: date-time createdByUserId: type: string format: uuid nullable: true canvases: type: array items: type: object properties: canvasId: type: string format: uuid projectId: type: string format: uuid canvasTitle: type: string nodeId: type: string format: uuid nullable: true required: - canvasId - projectId - canvasTitle tags: type: array items: type: object properties: id: type: string format: uuid name: type: string color: type: string required: - id - name - color nodeId: type: string format: uuid nullable: true versionCount: type: integer minimum: 0 favoriteNodeId: type: string format: uuid nullable: true favoriteVersionId: type: string format: uuid nullable: true favoritedByUserId: type: string format: uuid nullable: true required: - assetId - filename - source - fileType - contentType - fileSizeInKb - durationInMs - previewUrl - assetUrl - createdAt - createdByUserId - canvases - tags total: type: integer minimum: 0 folderId: type: string format: uuid canvasId: type: string format: uuid source: type: string enum: - upload - generated fileType: type: string enum: - image - video - audio - pdf - text tags: type: string required: - query - results - total '401': description: Missing, invalid, expired, or revoked API key. content: application/json: schema: type: object properties: statusCode: type: integer error: type: string message: type: string required: - statusCode - message '403': description: '403' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached — retry after the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: type: object properties: statusCode: type: integer error: type: string message: type: string retryAfterSeconds: type: integer required: - statusCode - message components: securitySchemes: apiKey: type: http scheme: bearer description: 'A Melius API key (`mel_...`), sent as `Authorization: Bearer `.' teamId: type: apiKey in: header name: x-team-id description: The team (workspace) to act on. Defaults to the key's team when omitted. ````