What you can ask for
This is the complete list of what an assistant connected to StoryFolder can do. You never have to name any of it — you ask for what you want and it picks. The list is here for when you want to know exactly where the edges are.
9 of the 14 abilities only look at your library. 5 of them change it, and those 5 are the ones read-only mode switches off.
If you would rather see this in action, things to try has real requests and what came back.
What it can look at
See your whole library
Reads only
The projects you have, with how long each one is, how many shots it holds, and where it is filed.
"What is in my StoryFolder library?"
The detail — list_projects
List the video projects in the StoryFolder library. Returns a summary per project (id, name, duration, shot count, folder) — use get_project for shot boundaries and metadata. StoryFolder must be running.
| Argument | Type | What it does | |
|---|---|---|---|
query | string | optional | Case-insensitive substring match on the project name. |
folder_id | string | optional | Only projects filed in this folder. |
limit | integer (1–200) | optional | Default 50. |
include_archived | boolean | optional | Include projects in the Trash. Default false. |
Open one project
Reads only
Every shot in a project, with its timecode and whatever notes you have written on it.
"Walk me through the makerspace video."
The detail — get_project
One project in detail: its shot boundaries with timecodes, and the metadata attached to each shot. Use the shot list to pick frames for get_frames or set_frame_metadata. Each shot carries two identifiers: "index" is 0-based and is what you pass back to these tools, while "shot_number" is the number the user sees in StoryFolder and in exported filenames. Shot 1 is index 0 — always tell the user the shot_number, never the index.
| Argument | Type | What it does | |
|---|---|---|---|
project_id | string | required | From list_projects. |
Look at the shots
Reads only
The actual pictures, up to twelve at a time, so the assistant can see what is in them rather than guess.
"Show me shots 1 to 4 of the hoodie ad."
The detail — get_frames
Return frames from a project as images so you can see what is in the video. Give either shots (the centre frame of each shot) or explicit times in seconds. At most 12 per call. Shots can be named either way: "shots" takes 0-based indices, "shot_numbers" takes the numbers the user sees. Shot 1 is index 0.
| Argument | Type | What it does | |
|---|---|---|---|
project_id | string | required | — |
shots | array of integer (items min 0) | optional | Shot indices (0-based, the "index" from get_project). The centre frame of each is returned. |
shot_numbers | array of integer (items min 1) | optional | The same shots named the way the user sees them (1-based, the "shot_number" from get_project). Use this to avoid converting. Give either shots or shot_numbers, not both. |
times | array of number (items min 0) | optional | Explicit times in seconds. Use instead of shots for a specific moment. |
width | integer (64–1920) | optional | Pixel width. Default 512 — larger costs proportionally more. |
Search your notes
Reads only
Find shots by what you have recorded on them — in one project, or across everything in one go.
"Which shots have nothing in the Emotion field?"
The detail — search_frames
Find the shots that match — in one project, or across the whole library. Omit project_id to search every project that is not in the Trash; that is ONE call, not one per project. "query" searches BOTH the metadata a human typed AND the transcript of what is spoken, so "which shots mention the hoodie sale?" is one call and you do not have to know which it was. Transcript matching is multi-word and fuzzy — a phrase runs across pauses and cuts, and a plausible mishearing still matches — so every match says whether it came from "metadata" or "transcript", and a transcript match carries the words actually spoken and whether they were an approximate match. Quote from "transcript" rather than paraphrasing. Use "search" to restrict to one source. Match one field with "field" (plus optional "value" and "match"), or several conditions at once with "criteria" — all of which must hold. A field title that two categories both use matches both. Every match names its project and carries "index" (0-based, what get_frames takes) and "shot_number" (what the user sees — shot 1 is index 0).
| Argument | Type | What it does | |
|---|---|---|---|
project_id | string | optional | One project, from list_projects. Omit to search every project that is not in the Trash. |
query | string | optional | What to look for. Matched case-insensitively against every metadata value (as a substring) and against the transcript (multi-word and fuzzy). Several words are matched as a phrase. |
search | all | metadata | transcript | optional | Which source "query" searches. Default "all" — both metadata and transcript. Use "metadata" or "transcript" to restrict it. Ignored when there is no query. |
field | string | optional | Field title or id, or one of favorite / hidden / posterTime. |
value | any | optional | The value to compare against. How it is compared is up to "match". |
match | contains | equals | one_of | is_set | not_set | optional | equals (default when value is given), contains (substring), one_of (value is a list), is_set (default when value is omitted), not_set (the field is not filled in on that shot). |
criteria | array of objects | optional | Several field conditions, ANDed — a shot must satisfy all of them to match. |
limit | integer (1–200) | optional | Most matches to return. Default 50; the response says whether it truncated. |
List your folders
Reads only
The folders you can file projects in.
"What folders do I have?"
The detail — list_folders
The folders projects can be filed in. Use a folder id with list_projects or update_project.
Takes no arguments.
See what you can tag with
Reads only
Your note categories and the fields inside them, including the options a dropdown allows.
"What can I tag shots with?"
The detail — list_metadata_fields
The metadata schema: categories and the fields inside them, with their types and options. Field titles from here are what set_frame_metadata and search_frames accept.
Takes no arguments.
Check on an export
Reads only
Whether a job finished — and whether it actually wrote any files, which is not the same thing.
"Did that export finish?"
The detail — get_export_job
The state of one export job. Pass wait_seconds to wait for it to finish instead of polling — the wait ends as soon as StoryFolder reports the job changed, or when the time runs out. A finished job also lists the files it wrote, relative to its location; check "files_written" before telling the user an export succeeded, because a job can finish having produced nothing. "progress" is the percentage of the CURRENT task and only means anything while one is running.
| Argument | Type | What it does | |
|---|---|---|---|
job_id | string | required | — |
wait_seconds | integer (0–120) | optional | Wait up to this long for the job to finish. Default 0 (answer immediately). |
See recent exports
Reads only
What you have exported lately, newest first.
"What have I exported this week?"
The detail — list_export_jobs
Export jobs, newest first. Optionally only those for one project.
| Argument | Type | What it does | |
|---|---|---|---|
project_id | string | optional | — |
limit | integer (1–100) | optional | Default 20. |
Review what changed
Reads only
A project's restore points, newest first, flagging which ones an assistant made.
"What have you changed in this project?"
The detail — list_versions
The restore points StoryFolder captured for a project, newest first, including which ones an assistant made. Use it to check what your own edits changed — the user restores a version from the Version history window in the app.
| Argument | Type | What it does | |
|---|---|---|---|
project_id | string | required | — |
limit | integer (1–100) | optional | Default 20. |
What it can change
Every one of these goes through the same path the app itself uses, so the change lands in Version history, tagged as made by an assistant, and you can undo it from there.
Rename or re-file a project
Editing — off in read-only mode
Change a project's name or description, or move it into a different folder.
"Rename this to Pacific Hoodie, cut 3."
The detail — update_project
Change a project's title, description, or the folder it is filed in. Every change is recorded in StoryFolder's Version history, tagged as made by an assistant, so the user can undo it.
| Argument | Type | What it does | |
|---|---|---|---|
project_id | string | required | — |
title | string | optional | The project name shown in the library. |
description | string | optional | — |
folder_id | string or null | optional | Folder to file it in, or null for none. |
Add a note field
Editing — off in read-only mode
Create a new field to tag shots with, and the category to hold it if you do not have one yet.
"Add a Location field with the options Studio, Street and Home."
The detail — create_metadata_field
Add a metadata field to the schema so shots can be annotated with it. Creates the category too if it does not exist yet.
| Argument | Type | What it does | |
|---|---|---|---|
category | string | required | Category title or id. Created if it does not exist. |
name | string | required | The field title, e.g. "Lens" or "Location". |
type | text | checkbox | dropdown | tag | file | date | slider | optional | Default "text". |
options | array of string | optional | Choices, for dropdown and tag fields. |
description | string | optional | — |
Tag shots
Editing — off in read-only mode
Write a value onto one shot or many. A batch counts as one edit, so it is one undo.
"Mark shots 4 through 9 as B-roll."
The detail — set_frame_metadata
Write a metadata value onto one or more shots (or explicit frame numbers). Recorded in StoryFolder's Version history and attributed to an assistant, so the user can undo it.
| Argument | Type | What it does | |
|---|---|---|---|
project_id | string | required | — |
field | string | required | Field title or id from list_metadata_fields, or favorite / hidden / posterTime. |
value | any | required | The value to write. Arrays for tag fields, booleans for checkboxes. |
shots | array of integer (items min 0) | optional | Shot indices (0-based, the "index" from get_project). The value lands on each shot's start frame, which is where StoryFolder itself writes it. |
shot_numbers | array of integer (items min 1) | optional | The same shots as the user sees them (1-based "shot_number" from get_project). Shot 1 is index 0. Give either shots or shot_numbers, not both. |
frames | array of integer (items min 0) | optional | Explicit frame numbers, instead of shot indices. |
Import a video
Editing — off in read-only mode
Bring a video file from this computer into StoryFolder. It imports in the background.
"Import ~/Movies/interview-take-3.mov into my Client Work folder."
The detail — import_video
Import a video file from this computer into StoryFolder. Checks the file is readable first, then starts the import. Importing runs in the background — poll get_project until status is complete.
| Argument | Type | What it does | |
|---|---|---|---|
path | string | required | Absolute path to a video file on this computer. |
folder_id | string | optional | Folder to file the new project in. |
title | string | optional | Project name. Defaults to the file name. |
Start an export
Editing — off in read-only mode
Queue a PDF storyboard, images, clips, a shot list, a transcript, or a shareable link. It never holds up the conversation.
"Export a PDF storyboard of the hoodie ad."
The detail — create_export
Queue an export of a project. Returns a job id immediately — exports take minutes, so this never blocks. Poll get_export_job with that id, or give it wait_seconds to wait for progress. Leave "location" out unless the user named a folder: StoryFolder then exports to its own default folder under the user's Documents and tells you the absolute path it used. Do not invent a path — a folder that does not exist on this computer is refused here.
| Argument | Type | What it does | |
|---|---|---|---|
project_id | string | required | — |
outputs | array of storyboard | images | clips | timecode | transcript | onlineStoryboard | required | What to produce: storyboard (PDF), images (PNG per shot), clips (video per shot), timecode (XLSX shot list), transcript (SRT/VTT/TXT), onlineStoryboard (shareable link). |
location | string | optional | Absolute path to an output folder on THIS computer. Optional — omit it and StoryFolder uses its default export folder, and reports the path it used. Only pass a path the user gave you or one you have confirmed exists. |
transcript_formats | array of srt | vtt | txt | csv | fountain | optional | Which transcript formats to write. Default srt and vtt. |
clip_speed | fast | slow | optional | Clip transcode preset. Default fast. |
Two things worth knowing
Shot numbers. You say "shot 5" and you get shot 5 — the numbering is handled for you. If an assistant ever quotes a number that's one off from what you see, here's why.
This page tracks the connector. It is generated from the connector's own definitions, so it describes exactly what version 0.3.0 offers your assistant — not a hand-written summary that drifted.