Find any resource in Clueso by type, optionally filtered by name or exact id. One tool for listing and searching across the workspace.
type:
• projects | folders | tags | clueprints | workspaces
(tags = the workspace's project tags, each with `color` and `project_count`. Apply them with update_project. Each project result carries its `tags` (names); filter projects by them with `tags` + `tag_match`.)
• backgrounds | voices | fonts | image_gen_style_packs | code_style_packs | element_components | animations | avatars
• clip_templates — one-clip intro/outro/chapter-break covers (a clueprint is a whole video). Replies in sections, not items: `defaults` {intro, outro}, `folders` + `templates` (this workspace), `library_templates` (Clueso's; unnamed, so refer to one by `template_id`). `source`: 'defaults' | 'org' | 'library' | 'all' (default); `clip_label`: intro | outro | chapter break | others; `folder_id` narrows the workspace's templates. Insert one with add_clips(kind='template').
(voices carry `gender`, `tags`, `accent`, `engine` and a `description` of tone, age, accent and use (the catalog's own, else ElevenLabs' labels: "calm, middle aged, american, male — good for narration"; a voice with neither has none), which is the field actually worth choosing on. `tags` is a small closed vocabulary, so it groups voices rather than telling them apart. The workspace's saved voices (its own picks, the editor's Saved tab) carry `saved: true` and its custom voices (clones made for it) `custom: true`; source='saved' lists only the saved ones, source='own' both. Choose deliberately: voiceover is the film's clock, and regenerating speech later rescales the clip and every element time and keyframe with it.)
• images | videos | music | sfx — media; each result carries a `source` ('org' = your saved-media library, 'stock' = a stock/curated provider). Scope with `source`, pick the library with `provider` (see below). Stock results are a short described shortlist — pick the best fit and use its `src`. Stock video results also carry `safe_src` and a `video_files` tier list with one entry marked `recommended` — use `safe_src` (or the recommended tier) in add_elements; tiers above 1080p can exceed its ~200MB source cap and fail. For a Freesound music/sfx result, `src` is an OPAQUE handle (not a playable URL) — pass it straight to add_audio and the original is fetched + hosted by Clueso server-side; `detail:'full'` adds a `preview_url` so you can tell what it sounds like.
• brand_kits | icons
(brand_kits = this workspace's brand kits, default first, each with `is_default`, `source_domain`, `accent`, `title_font`, `logo_count`, `icon_library`, `updated_at` and `edit_url` (where the user edits it). Nothing is implicit: pass a kit's id as get_design_guide's brand_kit_id to read it, or as create_project / update_project brand_kit_id to build a project with it, so one project can use kit A and another kit B. `detail:'full'` returns each whole kit as JSON: palette by role, logos (id, url, kind, for_background, aspect, sample), fonts (family, role, weights, the font_setting to pass), icons, captions, voices, guidelines, company knowledge, reference images. `logo_count` counts the brand's real logos; generated samples are `sample_logo_count`.)
(icons = icon names in the brand kit's icon library for `query`, drawn the kit's way (style, stroke, color), with the icons the kit pins for that concept first. A kit with its own uploaded icon set: use its own icons first (get_design_guide 'brand.icons'); the library is the fallback for what they do not cover, and the reply says so. The kit is project_id's (else the workspace default) or brand_kit_id's. The reply names the set and carries `usage`, the exact line to draw one. One icon library and one style per video: an icon missing from the kit's set → search the set again with other words; never switch sets. `library` searches another set, only for a video that uses no other. `detail:'full'` adds each icon's `src`, an SVG in the kit's color for add_elements element_type 'image'.)
(fonts = the typefaces THIS WORKSPACE has uploaded as brand fonts (add one with upload_file purpose: 'font'), each with `id` and `name`. Pass a returned `name` as a text element's `font_setting.font` — that is the whole contract; you never pass the url. This list is the ONLY way to know which non-Google families actually exist here: a font_setting naming a family in neither this list nor Google Fonts silently renders Inter, with no error and a confident-looking `layout.text_width_px` measured against the wrong face. Check here before building a layout on a brand typeface.)
(animations = animations to place, two kinds, the project's own first (`project_id`; a `query` searches every project's). `kind: 'page'`: HTML animations from the workspace library and Clueso's shared tiers; rows: `id` (the `animation` edit_animation and animation.place take), `title`, `site`, `scope`, `tier`, `rev`, `probe`, `uses`, plus `entries` when it has more pages and `project_id` for a project's. `kind: 'canvas'`: this workspace's older canvas Mograph kits (tier 'org'); rows: `ref`, `title`, `entries`, `scope`, `rev`, `uses`. Place a canvas kit as it is with add_elements(element_type='animation', type_data: {animation: ref, entry}); editing it with edit_animation converts it to an HTML page first. Filter with `tier` ('org' | 'official' | 'community'); read a page with read_animation (a placed canvas element too).)
(image_gen_style_packs = generation style presets for generate_media kind='image' style_id, each with `ready`; code_style_packs = looks for animation code, each with its `examples` count; `id` + `query` (what you will animate) reads one: its style_prompt and closest examples (code, description, params) whole, to match when you write the code; element_components = saved components (e.g. animations) from THIS WORKSPACE only — there is no community library for components (unlike clueprints); each reports param_keys. Insert one AS-IS with add_elements(component_id=...), or generate a variant from it with base_component_id.)
(avatars = AI presenter looks for add_elements element_type='avatar' — pass the id as type_data.avatarId. No query lists one default look per character; a query matches character and look names and returns every matching look. Each carries `styles`, `engine`, `credits_per_minute` and a `preview_image`.)
Filters (all optional):
• query — for stock media it's the search phrase (real semantic search for provider='clueso'; provider keyword search otherwise). For clueprints a query runs a relevance-ranked search across your workspace + the global community library (search_summary, relevance_reason, tags, is_community, fork_count). For everything else it's a case-insensitive name substring.
• provider — which stock library to search (ONE call, no merging). Choose by strength:
images → 'pexels' (default; realistic photography) or 'pixabay' (illustrations, vectors, icons, clip-art — set image_type)
videos → 'pexels' (default; real-world footage) or 'pixabay' (motion graphics — set video_type='animation')
music → 'clueso' (default; our curated, brand-safe library with the best descriptions/search) or 'freesound' (niche/genre tracks)
sfx → 'freesound' (default; vast sound-effect library) or 'clueso' (curated sfx)
music/sfx options for the user → search BOTH ('clueso' and 'freesound', same query and filters, in parallel) and offer the best 3-5 across them; picking one yourself → 'clueso' first, 'freesound' when it has no fit
• image_type — images + provider='pixabay': 'photo' | 'illustration' | 'vector'
• video_type — videos + provider='pixabay': 'film' | 'animation'
• id — exact id; returns just that one record (any type; for music/sfx a stock result's id or src, looked up directly)
• source — media: 'org' | 'stock' | 'all' (default = org + stock). Under 'all', stock is appended only when a query is given. sfx is stock only. voices: 'saved' = only this workspace's saved voices, 'own' = its saved and custom voices (neither searches the catalog).
• folder_id — projects + saved media (images/videos/music): restrict to a folder; projects: 'root' = outside every folder
• engine / language — voices only
• tags — voices: descriptive words ('calm', 'british', 'narration'); any one matches. `query` matches voice NAMES only, so a description goes here. A query or tags also searches the shared voice catalog (each row's `source`: 'org' or 'catalog'); without either only this workspace's voices list. projects: keep projects carrying the named tags (names match ignoring case; list them with find(type='tags')).
• tag_match — projects only: 'any' (default) = at least one of the tags, 'all' = every one, same as the home page's Tags filter. A name the workspace doesn't have matches nothing.
• creator_id / mine_only — clueprints only
• orientation — stock images/videos: 'landscape' | 'portrait' | 'square'
• color — stock images: a color name/hex, e.g. 'blue'
• size — stock videos: 'large' | 'medium' | 'small'
• min_duration / max_duration — stock videos + freesound audio: length bounds in seconds
• page / limit — paging for large sets (projects, components, clueprints — a clueprint list is sliced to the limit with no marker when more exist, so page through rather than assuming the first page is everything). `limit` caps every type, stock media included (a stock shortlist has no further pages); a capped reply says how many it left out.
• music/sfx filters — only for what the brief actually says; `query` stays the main signal (2-5 words for how it SOUNDS: "warm acoustic upbeat", "fast air whoosh", never the video's topic). `mood` / `genre` / `energy` rank (a miss is never hidden); `vocals:false`, `bpm_min` / `bpm_max`, `avoid` and `sfx_type` filter (a track with no label for it still passes). Under voiceover pass vocals:false. `similar_to` = an earlier result's id (a Freesound src also works; a clueso library src link doesn't) → sounds like it, instead of the text search (e.g. when the user rejects a pick); it takes none of the other filters. Music/sfx results carry the matching labels (mood, genre, energy 1-5, vocals none|wordless|lyrics, sfx_type, bpm) — choose on them and the description, never the name alone.
• detail — voices, music, sfx, fonts, brand_kits, icons: 'compact' (default; the essentials, 8 rows unless you pass limit; fonts and brand_kits list them all) or 'full' (every field: preview urls, thumbnails, attribution, rhythm detail, full descriptions; a brand kit's every section)
Returns { type, count, items: [{ id, name, type, ... }] }, plus total and has_more for projects and folders. Feed the returned id straight into the consuming tool (set_voice, update_clips background, generate_media style_id, add_audio src, use_clueprint, etc.). Any `duration` on a returned item is in SECONDS — pass it straight to add_audio's source_duration.
