Locate the project and folders
- Call
workspaces_listto find workspaces available to the authenticated user. - Call
projects_listwith the selectedworkspace_id. - Call
projects_getwith the chosenproject_ids. Itsroot_directory_idis the starting point for files at the top level. - Use
directories_listandassets_listwith aparent_idto inspect the relevant folders. Follow pagination on tools that expose it.
Search using the available channels
Callassets_search_capabilities with the project_id before constructing a search specification. It describes the available visual, transcript, document, and filename channels and the metadata filters the project supports.
Pass a supported spec to assets_search. Discover valid option, Face, and user IDs instead of guessing filter values; entities_list helps find recognized people. assets_search returns up to limit ranked assets (20 by default, at most 50), fewer when they do not fit in one response: when has_more is true, call again with offset increased by returned for the rest. Each match names the signal id it matched. An asset whose returned_matches is below its available_matches has more matches than shown.
To search within one known asset, or to list all of one asset’s matches, pass its asset_id and a spec to asset_content_search, starting at match_offset 0. It returns that asset’s matches that fit in one response: when match_offset plus returned_matches is below available_matches, call again with match_offset increased by returned_matches.
Read the surrounding context
Keep the asset ID and time range attached to each observation. Timecode conversion can return null with a reason when a source has no usable frame rate. Do not substitute invented timecodes.
Organize selects without moving the source
Create a named collection withcollections_create, then add the chosen asset or directory IDs with collections_items_add. A collection groups references; it does not create local files or an editor timeline.
Use fs_items_copy if the work needs separate cloud copies. It returns a background job ID. Use fs_items_move only when the intention is to change the source location; inspect reported name conflicts before supplying conflict resolutions.
For metadata, discover fields with metadata_attributes_list, read current values with asset_metadata_get, and write supported values through asset_metadata_set. Reuse existing fields when they already describe the information.
Continue in an editor
The agent can now use the Aspect CLI to mount or download media and an editor integration to work with the timeline. Follow Agentic Video Editing to prepare mounted proxies and pin originals while cutting. To turn your selects into generation references, follow Canvases and generation. You can generate a result directly in the project or place existing assets on a canvas and connect them to generation nodes. Readcanvas_content_get before changing an existing graph, and use generations_run_wait to retrieve completed results.