Naming an item
Every item has one canonical id and an 8-character ref, likeXC4WBAX5, that users can copy from the app. Either one works wherever a tool asks for an item, exactly as it was returned. A generation returns a job id. The item it makes gets its own id when the output is ready, and the job id also works as a ref for that item.
Getting media in
import_media has one mode per source:
urlfor hosted files, up to 20 per call. Files are deduplicated by content, and each is reported as imported, duplicate or failed. A download that takes longer than about 20 seconds continues as a job.filefor bytes in the call, base64, up to 3 MB.localfor absolute paths on the computer running the desktop app. Nothing is uploaded during the call. With the workspace’s cloud sync on (the default), the file is also copied to the cloud while the owner’s storage has room.presignandconfirmfor a file the caller uploads itself with a PUT: up to 5 GB of video, 500 MB of audio, 20 MB for an image, 25 MB for a document. A larger video can be added throughlink.linkfor a page where the user can add files from a computer or a phone. It returns alink_id, andsearch_librarywithupload_linklists the files added through that page.
Reading media
search_libraryfinds items by text over descriptions, tags, transcripts and what pictures show, with filters for type, folder, dates, labels, fields, storage and source, paged withnext_cursor.duplicates_offinds files nearly identical to one item.search_footagefinds moments inside videos and recordings, by what is seen or said, as start and end times in seconds of the source.get_itemsreturns everything stored about up to 25 items: description, tags, fields, comments, provenance, lineage, group, technical data, and which analyses are stored.inspect_mediareturns the actual picture: an image, or a video as frames in one of several layouts, with the words spoken in that span when a transcript exists. A title or description is text someone wrote, while the frames show the file itself.transcribe_media,detect_beats,speakers,inspect_colorandread_documenteach read one thing from a file, andinspect_mediawith apromptasks a model a question about a video or audio file. Transcripts, beats, speakers and document text are stored on the item, so reading them again is free, while eachpromptis a new paid read.
Writing metadata
update_items sets name, description, tags, typed field values and lineage on up to 25 items per call, each item separately. A failure on one item is reported alongside the results for the others. made_from records what an item was derived from. Items shown together form a group (organize_items group).
Structure
Structure is optional.organize_items creates all of it in one batch, in a fixed order, so one call can create a folder path and move items into it.
- A folder is where an item is kept. Paths like
campaigns/julyare accepted wherever a folder is named. - A label is a tag shared across the workspace, used for filtering.
- A field is a typed column across the workspace. Boards are built on select fields, and calendars on date fields.
update_itemssets values by field name and refuses a name that does not exist. - A board (
manage_boards) is a select field whose options are its columns. Placing a card in a column sets that field. A calendar (manage_calendars) is a date field with a time, channels and a status of its own. - A group links items shown together: a research document and the posts it is based on, a set of variants, slides. Each stays its own item in the library.
- Favorite and hide are per item. A hidden item is removed from the feed but stays in the library.
Brand kit
manage_brand_kit reads and writes the workspace’s brand kits: colors, fonts, written direction, logos, pinned templates, and words the workspace spells in its own way, which transcripts are corrected to. The free plan includes one kit. get_workspace_overview says whether a brand kit exists.
Public links
manage_public_links builds a page from chosen items that anyone can open without an account, with a layout of blocks and a record of what visitors wrote. Settings changes go live right away, while a layout change stays a draft until publish. Public pages are hidden from search engines. Deleting a link removes the link and its activity, but not the media.
