Find resources
findFind 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 (the built-in set when it has none) 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Exact id — returns just that record. | |
| mood | No | music/sfx: moods to rank first. | |
| page | No | Page (default 1) — projects/element_components/clueprints. | |
| size | No | stock videos only: minimum resolution bucket. | |
| tags | No | voices: descriptive words (a list or comma-separated), any one matches. projects: tag names; keeps projects carrying them (see tag_match). | |
| tier | No | animations only: 'org' (this workspace), 'official' (Clueso's) or 'community'. Default all three. | |
| type | Yes | Resource type to find. | |
| avoid | No | music/sfx: moods or genres to exclude. | |
| color | No | stock images only: color name or hex, e.g. 'blue'. | |
| genre | No | music: genres to rank first. | |
| limit | No | Page size, and a cap on every type, stock media included (default 8 for voices, music and sfx, every font for fonts, 50 otherwise; a '_more' item or a note says when more exist). | |
| query | No | Case-insensitive substring match on name. | |
| detail | No | voices, music, sfx, fonts, brand_kits, icons: 'compact' (default) — the essentials to choose and use one (voices: id, name, gender, accent, engine, tags, a short description; music/sfx: id, name, src, duration, bpm, tags, a short description; fonts: id, name; brand_kits: id, name, is_default, accent, title_font, logo_count, icon_library; icons: names); 'full' — every field (preview urls, thumbnails, attribution, rhythm, full descriptions; for brand_kits every section of the kit; for icons each one's src). | |
| energy | No | music: 1 still, 2 gentle, 3 steady, 4 driving, 5 intense; ranks. | |
| engine | No | voices only: 'eleven' | 'cartesia' | 'google'. | |
| source | No | media types (images/videos/music/sfx): where to search — 'org' (your saved workspace media), 'stock' (stock library — images/videos via Pexels, music from Clueso's catalog), 'all' (both; default). sfx is stock-only. clip_templates: 'defaults' | 'org' | 'library' | 'all'. voices: 'saved' (only this workspace's saved voices) | 'own' (its saved and custom voices). | |
| vocals | No | music: false = instrumental only, true = with vocals. | |
| bpm_max | No | music: tempo ceiling. | |
| bpm_min | No | music: tempo floor. | |
| library | No | icons only: an icon set id ('lucide', 'ph', 'tabler', ...) other than the kit's. One set per video, so only for a video using no other. | |
| language | No | voices only: e.g. 'en'. | |
| provider | No | stock media: which library to search (exactly one). images/videos: 'pexels' (default — polished real-world photos & footage) | 'pixabay' (illustrations, vectors, clip-art, icons + more variety; pair with image_type/video_type). music/sfx: 'clueso' (default for music — our curated, brand-safe, well-described library, best semantic search) | 'freesound' (huge community library; best for niche music and sound effects — default for sfx). Offering the user music/sfx options → one call per library, both. | |
| sfx_type | No | sfx: the kind of effect. | |
| folder_id | No | projects/images/videos/music/clip_templates only: restrict to a folder. | |
| mine_only | No | clueprints only: only ones I created. | |
| tag_match | No | projects only, with tags: 'any' (default) = at least one of the tags, 'all' = every one of them. | |
| clip_label | No | clip_templates only: one kind of cover. | |
| creator_id | No | clueprints only: filter by creator id. | |
| image_type | No | stock images + provider='pixabay' only: 'photo' | 'illustration' | 'vector' (flat/drawn graphics, icons, clip-art). Use illustration/vector for graphic looks; photo (or Pexels) for realism. | |
| project_id | No | animations: also list this project's own animations, first. icons: search this project's brand kit's icon set. | |
| similar_to | No | music/sfx: an earlier result's id (a Freesound src also works); returns sounds like it. No other filters with it. | |
| video_type | No | stock videos + provider='pixabay' only: 'film' (live footage) | 'animation' (motion graphics). | |
| orientation | No | stock images/videos only: result orientation. | |
| brand_kit_id | No | icons only: search this brand kit's icon set (an id from find(type='brand_kits')) instead of the project's. | |
| max_duration | No | stock videos + freesound audio: maximum clip length in seconds. | |
| min_duration | No | stock videos only: minimum clip length in seconds. |