Skip to content

Reference

Tools

What an agent can call. SPREVA lists 49 tools, and the ones for the Studio and AI images need a plan that includes the Studio.

All tools

  • fetch

    Read one thing in full

    Reads a post, file, campaign, queue, account or Studio project from its link or id, or a page of SPREVA's reference.

    Risk
    Low
    Reads only
  • overview

    Workspace overview

    The first call in a conversation: the time zone and clock, what needs attention, what goes out next, the accounts, queues and campaigns, and what the plan allows.

    Risk
    Low
    Reads only
  • list_workspaces

    Your workspaces

    Lists the workspaces this connection can work in, with your role and time zone in each and which one calls are made in now.

    Risk
    Low
    Reads only
  • switch_workspace

    Switch workspace

    Moves the conversation to another of your workspaces, by name or link, when the connection was allowed in all of them. The calls that follow use that workspace's accounts, media and agent permissions.

    Risk
    Low
  • save_workspace

    Change the workspace's settings

    Renames the workspace or changes its time zone, the language media descriptions are written in, and whether new uploads are described automatically. Owners and Admins can. A new time zone does not move posts already scheduled.

    Risk
    Medium
  • list_members

    The workspace's people

    Lists the members with their email and role, and the invitations still waiting, with when each link expires.

    Risk
    Low
    Reads only
  • invite_member

    Invite someone

    Invites a person by email with a role, always after a preview to confirm, since it emails them and may take a seat of the plan. Someone who already has a SPREVA account at that address joins at once. Owners and Admins can; an Admin cannot invite an Owner.

    Risk
    High
  • save_post

    Create or edit a post

    Writes a post for one or more accounts, with what differs per account, and sets when it goes out: a time, a queue's next slot, or a draft. In a workspace that requires approval, a time or a queue sends it for review instead, and it goes out once a person approves it.

    Risk
    Medium, High when it goes out in less than an hour.
  • publish_post

    Publish a post now

    Publishes a post on all its accounts, or again only where it failed. What already went out is never posted twice. In a workspace that requires approval, a post nobody approved is refused: send it for review with save_post and a time or a queue.

    Risk
    High
  • delete_post

    Delete a post

    Removes a draft, a scheduled post or a published one from SPREVA. A published post stays live on the networks.

    Risk
    Medium, High for a published post.
  • import_media

    Import a file into the library

    Brings an image or a video into the library from a public link, or from bytes the agent uploads.

    Risk
    Medium
  • update_media

    Rename, tag, file or describe a library file

    Changes a file's name, tags, folder or alt text, and can write the alt text from what the picture shows.

    Risk
    Medium, High when it writes the alt text with AI.
  • delete_media

    Delete library files

    Deletes one or more files (images, videos, audio) from the library, after a preview and a confirmation that show where each is used and the space it frees. Files used by unpublished posts or Studio projects are refused unless the agent is told to force it.

    Risk
    High
  • share_media

    Share a file or folder with other workspaces

    Lends a library file or a whole folder to your other workspaces as read-only references: nothing is copied, and they can use it in videos and posts but not change or delete it. Taking it back asks for a confirmation when videos or posts there use it.

    Risk
    Medium, High when taking back a file that videos or posts in another workspace use.
  • save_campaign

    Create or edit a campaign

    Creates or changes a campaign, and adds posts to it or takes them out.

    Risk
    Medium
  • save_queue

    Create or edit a queue

    Creates or changes a posting schedule: its name, time zone and weekly slots.

    Risk
    Medium
  • analytics

    How posts performed

    Totals against the period before, the top posts, the split by network and comparisons with their sample sizes, for the workspace, a campaign, an account or a post.

    Risk
    Low
    Reads only
  • refresh_metrics

    Refresh the numbers

    Reads a post's numbers, or an account's followers, from the networks right now instead of waiting for the usual schedule, and leaves that schedule alone. The same post or account can be refreshed again after five minutes.

    Risk
    Low
  • list_clippers

    Your clippers and their views

    The accounts associated with your clippers program, ranked by views in a period, with each one's network, handle and link, and the ones waiting for your decision first.

    Risk
    Low
    Reads only
  • clipper_posts

    One clipper account's posts

    What an associated account published since it joined, newest first, with views, links and dates. Takes the account's name, @handle, link or id.

    Risk
    Low
    Reads only
  • clipper_calendar

    What your clippers have scheduled

    The posts your clippers scheduled in SPREVA for the coming days, and the ones that went out that way, earliest first, with the account, the network and the link once they are out. Posts made on a network itself are not here.

    Risk
    Low
    Reads only
  • create_video

    Create a Studio video

    Starts an empty Studio project in a format, which the agent then builds. If a project with that name already exists it answers with that one instead of making a copy.

    Risk
    Medium
    Needs a plan that includes the Studio
  • narrate_video

    Narrate a Studio video

    Voices the script the agent wrote and places every word on the timeline. Uses AI credits, 1 per 100 characters.

    Risk
    High
    Needs a plan that includes the Studio
  • compose_video

    Build a Studio video from a markdown script

    Builds a whole explainer video from one markdown script: what is said, and what is on screen at which word. The narration is voiced, the look sets colours, entrances, transitions and sounds, the camera punches in on what enters, and captions and music are added. The result is a normal, editable Studio project. Uses AI credits, 1 per 100 characters of narration, and answers with a preview first. Rebuilding a project from a changed script voices it again only when the narration changed.

    Risk
    High
    Needs a plan that includes the Studio
  • match_media

    Match library files to a script

    For each line of a script, lists the library files that fit it best, by what they show, the words on them, what is said in them and their quality, with the moment of a clip that fits. Changes nothing and spends nothing.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • find_sfx

    Find a sound effect by what it does

    Lists the best three library sound effects for a moment of a video, by intent, emotion and energy rather than file name, with why each fits and the gentlest one first. When nothing fits well, or when asked, it makes a new sound with Spreva's own synthesiser, saves it in the library and lists it first. Spends no AI credits.

    Risk
    Low
    Needs a plan that includes the Studio
  • find_music

    Find music by feel, varied between videos

    Lists the best three library music tracks for a video, by mood, genre, energy and how well they sit under a voice rather than file name, with why each fits. Tracks the workspace's recent videos used rank lower and tracks the project already has are held back, so videos do not share one bed. Tracks not classified yet are queued for classification. Changes nothing and spends nothing.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • find_icon

    Find an icon by what it means

    Lists the Lucide icons that best match a few words in English, such as phone, security or growth chart, with their tags and the best match first, and says how to place one in a motion graphic: the icon block, which draws itself on, or path nodes in a raw scene. Changes nothing and spends nothing.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • create_sfx

    Create a sound effect

    Makes a new sound effect with Spreva's own synthesiser, from a few words in English or Portuguese or from a recipe the agent writes for full control. It is saved in the library, in the Generated sounds folder, and classified like any other sound, so it can be found and placed in a video. Spends no AI credits.

    Risk
    Medium
    Needs a plan that includes the Studio
  • score_video

    Score a Studio video with music

    Composes instrumental music made to the video: a quiet intro, a build, the drop exactly on the reveal and a resolution. It joins the library as music and goes under the project as the bed, lowered under the voice. Uses AI credits, 30 per started 30 seconds of video, and answers with a preview first.

    Risk
    High
    Needs a plan that includes the Studio
  • plan_edit

    Plan the edit of a Studio video

    Reads a Studio video (what is said, the shots and cuts, what is already there) and the library's classified sounds, picks the recipe for its kind of video (theory, list, news, tutorial, promo, podcast, vlog, story, highlights) and applies a complete edit in one step, as one saved version: every cut hard or with a transition and its sound, the look, captions, a hook, music that ducks under the voice, punch-ins, text and B-roll. Cutting a picture out of its background uses AI credits, so it is offered, never applied. Without apply it changes nothing and only describes the plan.

    Risk
    Low
    Needs a plan that includes the Studio
  • find_moments

    Find moments in a long video

    Shows what a long video says, sentence by sentence with its times, where it gets loud, what the picture shows, and the clips it would suggest, so the agent can choose the parts worth cutting. Changes nothing and spends nothing.

    Risk
    Low
    Needs a plan that includes the Studio
  • read_transcript

    Read a file word by word

    Reads the transcript of a video or audio file the way an editor does: phrases with their times and speakers, hesitations (um, uh) kept and marked, and the silences listed. Several files can be read together to compare takes, and a range can be listed word by word with each word's start and end. Changes nothing and spends nothing.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • make_clips

    Make short clips from a long video

    Cuts the parts you chose from a long video into short vertical Studio projects, one per part, with captions from what is said. Each one is a project to edit and export.

    Risk
    Medium
    Needs a plan that includes the Studio
  • edit_video

    Change a Studio video

    Edits text, timing, cuts, pictures, clips, effects and sound, and adds new elements, with the Studio's own editing operations.

    Risk
    Medium
    Needs a plan that includes the Studio
  • save_video

    Rename or file a Studio project

    Renames a project and/or files it in a Studio folder, or takes it out of its folder; several projects can be filed at once. Renaming needs the project's revision; filing alone does not change the video. It can also copy a project to another of your workspaces: its files are shared with that workspace read-only and its brand fonts are added there.

    Risk
    Medium
    Needs a plan that includes the Studio
  • delete_video

    Delete Studio projects

    Deletes one or more Studio projects, after a preview and a confirmation. Files exported from them stay in the library.

    Risk
    High
    Needs a plan that includes the Studio
  • preview_video

    See a Studio video's frames

    Draws the frames at the moments the agent names, exactly as the export will, so it can check what covers what before exporting. Changes nothing and spends nothing.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • inspect_media

    Look at a stretch of a source file

    Draws one picture of a range of an uploaded video or audio file: frames spread evenly over it, the waveform of its sound with the pauses shaded, and the words said where they are said. Changes nothing and spends nothing.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • compare_video

    Compare two versions of a Studio video

    Lists what changed between two versions of a project: each element added, removed or changed, and what changed in it. It can also show both versions at the same moment. Changes nothing.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • restore_video

    Restore a version of a Studio video

    Takes a project back to one of its versions. The result is kept as a new version, so the restore can be undone too.

    Risk
    Medium
    Needs a plan that includes the Studio
  • review_video

    Review a Studio video

    Checks a project the way the Studio's own AI editor checks its work, and lists what to fix, worst first. It marks what the export will fix by itself.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • render_video

    Export a Studio video

    Exports a project to an MP4 or a PNG in the library, ready to go in a post. First it brings the project to the quality floor by itself (captions, a hook, music under the voice, transitions inside their caps) and keeps that as a version called Quality pass; it never touches what you made by hand.

    Risk
    High
    Needs a plan that includes the Studio
  • generate_image

    Generate an image

    Makes a new image from a description, in one of the workspace's styles if asked. Uses 10 AI credits. If the request is about pictures the library already has, it lists them first and spends nothing.

    Risk
    High
    Needs a plan that includes the Studio
  • mascot

    Choose the mascot

    Reads or sets the workspace's mascot: an animated SVG host that speaks, blinks and takes poses in a video. Free, no AI credits. Pick a built-in one, tint it with the brand colours or use your own drawing.

    Risk
    Medium
    Needs a plan that includes the Studio
  • use_skill

    Read the workspace's editing skills

    Lists the workspace's editing skills (a creator's playbooks: a look, a pacing, a recipe) or reads one in full, so the agent follows it when it makes or edits a video.

    Risk
    Low
    Needs a plan that includes the Studio
    Reads only
  • save_skill

    Keep an editing skill

    Creates, changes, imports from a SKILL.md or deletes an editing skill of the workspace. Its description decides when it is used.

    Risk
    Medium
    Needs a plan that includes the Studio

The usual path

An agent starts with overview for the time zone, the clock and the accounts, finds things with search, reads one in full with fetch, and changes it with save_post or another tool. Every answer says what can be done next.

Names, not ids

Tools take what a person would say: an exact file name, an @handle, a campaign's name, or a link to anything in SPREVA, pasted from the browser or from an earlier answer. Searching is forgiving and changing is not: a name that matches several things comes back as a choice, and nothing is saved until one is chosen.

Reference for agents

An agent reads SPREVA's reference with fetch when it needs it, rather than carrying it in every call:

  • spreva://docs/platforms/tiktok, and one page per network: what it accepts, lengths and options.
  • spreva://docs/queues: times, time zones and queues.
  • spreva://docs/agent-permissions: risk levels, confirmations, revisions and request ids.
  • spreva://docs/studio/making and spreva://docs/studio/editing: building a video, on SPREVA only.