Siren

What each ad account has spent, its spending limit, what's left under it, and the platform's billing link. No app can add money to an ad account: to top up, give the human billing_url.

What needs the human now (rejected ads, spend spikes, account problems, cap pauses), and what cleared in the last 30 days.

The customer list and lookalike audiences on Meta: how many people Siren knows, each audience's size and status. Read only; the human makes audiences on the Ads page.

Whether autopilot is on, what it may do by itself (pause a weak ad, move a budget by up to 20%, inside the caps, once every 3 days per campaign) and whether the plan allows it (Scale). Read only: the human turns it on or off on the Ads page under Caps, never an agent.

Sales tracking: whether the Siren tag has been seen on the site, events this week, the Meta pixel, other platforms it sends to, Stripe, and money made back in 30 days (minor units). Read only.

Add a face to the people library. Siren crops it round in a few seconds (status cropping, then ready). Only upload people who agreed.

How the ads did: totals, each campaign and each ad with spend, impressions, clicks, results, click-through rate, cost per click and cost per result. Money is in minor units (cents).

The workspace's ads at a glance: spend today and this month against the caps, live campaigns, connected ad accounts, every campaign with its status and budget, and how many of Siren's suggestions are open. Call first for anything about ads. Ads need Pro and the owner's ads switch for this agent; a 403 scope_ads says where they turn it on.

Split tests: the ones running with each version's numbers, and every verdict so far (the winner, its rate, how sure).

Boost any post Siren made: it becomes a Meta ad with its own picture or video and caption, sent PAUSED. No credits; nothing spends until go_live_ad_campaign and the human's yes. Pass the run_id, or a post_id from list_posts (each row says boosted_campaign_id once it is). With neither it lists the posts that did best lately so you can pick one with the human. A post boosted before answers with that campaign.

Get a Stripe checkout link for more credits. Give the link to the human; they pay on Stripe and the credits land in about a minute. Nothing is charged by this call. Read the balance on get_account.

Ask Siren's clarifier whether a brief is specific enough to generate from. Returns ready=true/false plus follow-up questions. Use before create_campaign when the user's request is vague.

Create a Siren campaign from a plain-language brief — the full pipeline: plan, on-brand copy, deterministic render, verify. Returns the run; poll get_run until it finishes. Spends credits (image 10, an ad set of 3 images 20, video 25; voice or music-only is the same 25). Pass output_type to pin a film (list_films has the catalog); omit it and Siren picks. Optional scheduled_at (ISO-8601) queues a sequential post (X → Instagram → TikTok, or platforms you pass) when the render succeeds — requires Allow posting. Fails with a 402 upgrade message if the plan or balance can't cover it.

FILM KNOBS: voiceover (true narrated / false music only), direction (mood, pace, motion, music in one line), music (a bed id), media (upload_media URLs the film shows). Images ignore the film knobs: Siren writes and paints them from the brief and Brand DNA.

ANY BRAND: pass brand to make it for a brand that is not this workspace's own, e.g. brand={"name": "Acme", "site": "acme.com", "logo_url": "https://acme.com/logo.png", "primary": "#FF4400"}. Nothing of this workspace's identity leaks in.

The exact same request within 24 hours returns the run it already started, as it is now, with replayed=true and no new charge. Change the brief to make another.

Start the brand mascot: from a description (note, kind) or from a reference picture. Paid plans; 100 credits. Siren paints a hero in about a minute; poll get_mascot, show the human, then mascot_step keep (build the pose sheet) or retry (paint again, 3 tries). One mascot per workspace.

Apply or dismiss one of Siren's suggestions. One that raises spend answers needs_confirm first, like set_ad_budget.

Remove a clip from Brand DNA, file and poster included.

Delete one photo or video uploaded with upload_media. Only this workspace's uploads; a film that already rendered keeps its copy.

Remove a face from the people library.

Remove a product screenshot from Brand DNA. Does not delete Brand Memory.

The full contract for one film: what it is and when to hire it, its body JSON Schema, a reference body, the seed envelope, media slots (which fields take image/video URLs), the brand prefills (colours, logo, screens) and the override rules. Call it before writing a render_asset body.

Edit a finished ad creative in place. Only what the instruction names changes; faces, layout, lettering and every other pixel are kept, so you can chain edits (hair pink, then tail teal, then add a sign) without the picture drifting. About 15 seconds. 3 credits; an instruction that asks for a whole new look ("make it a comic", "make it cinematic") repaints at 10. Returns the NEW run: poll get_run until it is terminal and show the human the new image. Films are not edited this way: re-render them with render_asset. Every earlier version stays, so the human can go back to any of them.

Get the connected Siren workspace: plan, key scopes, auto-post setting, and daily limit. Call this first to learn what the account can do before generating. Empty asset_types / channels / connected_accounts lists mean UNRESTRICTED, not missing — never stop on them. Films render on every plan; credits are the only meter.

One ad campaign: its plan, the Page it runs as, and each ad with its creative (asset_url), shape, copy and status. Poll this after make_ads until every ad is ready, and after send_ads_to_platform until it is paused.

The spend caps every change must fit (a day and a month, across all platforms), what's spent this month and the room left. Caps are raised only by the human on the Ads page, never by an agent.

Get this workspace's Brand DNA: brand_name, brand_kind, overview, tagline, offer, features, products, audience, palette, logos, plus checks: what to fix before rendering (thin Brand DNA, a typed accent the brand's own work does not use). Call right after get_account; fix thin DNA first with update_brand_dna and upload_product_screen, or ask the human for the site. Not Brand Memory.

The workspace mascot: status (hero, keeping, frames, ready), the hero picture, tries left, and every pose frame with its URL. Null mascot = none yet.

How the posts did: totals (impressions, engagement, replies, engagement rate) and the top posts with views, likes and replies.

Get one run by id — full status, output text, asset URLs, caption, and any error. Poll this after create_campaign or render_asset until status is terminal. Wait poll_after_seconds between polls; progress and eta_seconds say how far along it is. A finished film carries film_check, advice only: when ok is false, show the human the video and the findings and let them decide. Re-render at most once, and only for a defect you can name in what you sent (a missing image, a wrong name). notices are plain-words notes on the request (e.g. it asked for a mood the brand's look does not wear): the asset is made as asked; pass the note to the human. A finished run carries caption: the post caption Siren wrote in the run's brand (or yours, if you passed one); show it with the asset. After post_run, posts[] carries each platform's status and, once it fires, the live URL and the caption that went out.

Turn a campaign on: real ad money starts. Always two calls. The first returns status needs_confirm and a summary (per day, the most this month, the caps): show it to the human word for word. Only when they say yes, call again with the confirm code. Inside the caps only.

Every ad campaign: platform, status (draft, launching, paused, active), daily budget, spend, clicks and results so far, plus the caps.

Siren's open suggestions from its daily review (pause an ad with no clicks, cut a costly one, give a winner more), each with its reason.

The brand's own clips in Brand DNA: name, what each shows, when to use it, tags, best moments with timestamps, poster and scan_status.

The film library, one ranked page at a time. Films sit on job shelves; pass job and the human's goal and hire from the top of the page. Each film says what it is, when to hire it, its length and shapes, fits_this_brand (with what is missing) and made_recently (this brand already got it: prefer another film on the shelf unless the human asked for that one). Page on with next_page. Want it all at once? all=true, or fetch the catalog file (https://api.mysiren.ai/api/v1/films.md, every film by shelf, also .txt/.json) and read it in steps. search= finds films by word. Then describe_film for the body. Videos are on every plan; credits are the only limit. Every film here is 25 credits. Platinum films (50 credits) are not in these pages: the answer's platinum section flags them, and list_platinum_films has the shelf.

Photos and videos uploaded with upload_media, newest first, with their URLs. Reuse a URL in create_campaign media or a film body.

The people library: team faces Siren can put in stills (name, role, team, status cropping or ready, round crop URL).

The platinum shelf: studio-grade films that match a top motion studio's craft, told as the brand's own story. Each costs 50 credits, every time (a normal film is 25). Offer one only when the human is making a big launch they genuinely want to go far; everyday posts and normal budgets use list_films. Say the price before you render. Ids end in -plt. Platinum needs a paid plan or a credit top-up: a complimentary plan sees it but gets 402 platinum_needs_paid_plan. voice MM = motion and music only (no voice-over question, no narration); MVM = motion, voice and music. Then describe_film for the body, same as any film.

Every post Siren sent or queued: platform, status, live URL, time, and counts by status (posted, queued, failed).

List the brand assets in Brand DNA: product photos, app screenshots, packaging. Each row has name, kind, description, use_when, tags, scan_status (scanning / ready / failed), device, theme, url.

List the workspace's generation runs (newest first): status, brief, channel, asset URLs, and caption. Page with offset to see them all.

The still style library, one ranked page at a time. Every painted still (an ad creative, poster, release card, App Store frame, thumbnail) is one style; Siren picks one when you don't. Styles sit on section shelves; pass section and the human's goal and take one from the top. made_recently = this brand already got that look, prefer another. To paint in a style, put its id in the create_campaign brief (asset_type card). The whole library as one file: https://api.mysiren.ai/api/v1/styles.md (also .txt/.json).

Make the plan's ads: a draft campaign per platform, and Siren renders each ad (spends credits like any video or ad creative; tell the human first). Nothing reaches the platform yet. Poll get_ad_campaign.

Move the mascot on: keep the hero, paint it again, or add a pose. Ask the human before keep, since it builds the whole sheet.

Pause (turn off) a campaign now. Always allowed: it only stops spend.

Siren drafts an ad plan from one prompt: goal, audience, budget inside the caps, platforms and the ads to make (shape, hook, headline, text). Nothing is made or spent. Show the human the plan, then make_ads. With test, the versions split one budget and the verdict rule is set before any spend.

Post a finished run's assets to the workspace's CONNECTED SOCIAL ACCOUNT. This is live, public distribution on the customer's channel — always confirm with the user before calling. Only works if the grant was authorised with posting allowed. Pass caption to own the words; it goes out verbatim. The call queues the post behind a short publish window (about two minutes, cancellable) rather than firing inline: poll get_run after that and read posts[].url for the live permalink and the caption that went out.

Render films from pre-formed SirenSeed bodies (advanced). FILMS ONLY: images are painted from a brief, so for any image, ad or creative call create_campaign with asset_type=card (a still here returns 422 stills_use_a_brief). Each item: {output_type, channel, seed_body, archetype?, family?, surface?, caption?, voice_id?, music?, direction?, brand_override?}. Prefer create_campaign unless the user has concrete seed JSON. Returns run ids, estimated_seconds and poll_after_seconds; wait that long, then get_run.

THE DIRECTOR: every film body is edited against Brand DNA before it renders. It keeps the film and your brand-specific lines, rewrites empty, generic or reference-body copy, and never touches media. director in the response says what changed. direction is a free line ("dark, club energy, fast") that steers words, pace and music. A film that cannot use what you sent returns 422 film_does_not_fit with a fix and films_that_fit.

ANY BRAND: put brand_override={"name": "Acme", "site": "acme.com", "logo_url": "https://acme.com/logo.png", "primary": "#FF4400", "accent": "#111111"} on an item to render it for a brand that is not this workspace's own. With a name it is a clean slate: none of this workspace's logo, mascot, font, handle, screenshots or stills are used. Media slots take only URLs you uploaded with upload_media.

Schedule a finished run to post at scheduled_at (ISO-8601). Shows in the customer's local timezone. platforms: x, instagram, tiktok, linkedin, youtube, or everything. Posts fire sequentially. Requires Allow posting. Prefer this over post_run when the user names a time. On create_campaign you can pass scheduled_at instead.

Send a ready draft to its platform: campaign, ad set and ads are created PAUSED. Nothing spends until go_live_ad_campaign. Poll get_ad_campaign: launching, then paused (or draft with launch_error).

Change a campaign's daily budget, inside the caps. Lowering applies now. Raising a live campaign answers needs_confirm first: show the human the summary, then call again with the code.

Look up Siren itself: where something is in the app (pages, tabs, buttons), how a feature works, plans, prices, credits and policies. Returns up to 3 sections, each with its docs link and its place in the app (e.g. Ads → Sales). Call it before telling the human where to click or what something costs; if it returns nothing, say you're not sure and point to https://mysiren.ai/docs. Read only.

Create a Studio profile on this API key. Returns generate curl and inbound hook URLs (Stripe, GitHub, Uptime Kuma, Product Hunt, generic). Passing delivery.social_account_ids turns on social delivery for the profile — that publishes, so it requires Allow posting.

Render a Studio data card from a type + body. Deterministic React, no paint. Optional live post after render. Returns run_id, image url, and post url when posted.

The design tokens behind a Studio design, for building in the same language: palette, fonts, radius and shadow as tokens; css (custom properties plus a Tailwind v4 @theme block); tailwind (a v3 theme); and skill_md, a short rules file to drop into the project so the agent keeps to it.

Call it once the version has been exported, so screens carries the rendered proofs and exported is true. Free and read-only: it reads a design, it does not render one. Honest about scope: palette, fonts, radius and shadow; no type scale or spacing ramp yet.

Change a Studio video by asking, as the human would in the chat. Only what the ask names changes; Siren replies with what it changed (before and after) and the new version number. Waits up to about 25 seconds for the reply. No credits are spent until studio_export. A greeting or a question gets an answer and no new version.

Render a Studio design or video to files. Spends credits like any render: a video 25 (platinum 50), a card 10, a set 10 a slide (an App Store set of 6 is 60), charged once. A card or a set waits for the render (about a minute) and returns every file in asset_urls, slide 1 first; a video returns the run id: poll get_run until it is terminal, then show the human the file or post it with post_run.

One Studio video: the chat so far (who said what, with diffs), every version, and which version is current.

Render a Studio card then queue a ScheduledPost at scheduled_at.

Start a video in Siren Studio from a description. Siren composes the first take (about 10 to 20 seconds) and replies with what it made; nothing is rendered or charged until studio_export. Returns the thread and Siren's reply. The human sees the same thread in Studio and can keep editing it there, or you can with studio_edit.

List Siren Studio's 33 React data-card types with family, description, and body schema. Use this before studio_card so the body matches.

The workspace's Studio videos, newest first: title, shelf, current version, and whether a human or an agent started it.

The whole Sales tracking setup as one Markdown brief for the site's developer: the tag with this workspace's key (before on every page), the sign-up and purchase calls, consent, how to check it on Ads → Sales, and where the tag goes in Next.js, React/Vite, Webflow, Framer, WordPress and Shopify. Read only. Hand markdown over as it is, or save it as SIREN-TRACKING.md.

Patch Brand DNA. Send only keys to change. Nested bags (offer, product_map, icp) merge. Examples: {tagline, overview, offer: {product_name, one_liner, features, who_its_for, primary_cta}, product_map: {offerings, how_we_work}, icp: {who_buys, pains}}. Does not read or write Brand Memory.

Edit an existing brand asset: name, description, kind, use_when, and the screenshot tags (screen_type, device, theme).

Add a product demo, walkthrough or footage to Brand DNA. With only the file, Gemini reads frames across the clip and writes what it shows, when to use it, tags and the best moments (scan_status scanning, then ready in about 15 seconds; poll list_brand_videos). Films play it when a brief names it ("launch film with our checkout demo"). Videos are for films; stills are painted from pictures.

Set the workspace logo in Brand DNA. Every render uses it.

Store a photo or video the human wants in a post, from an https URL or base64. Returns a workspace-owned URL to put in any media slot of a film body (describe_film lists the slots) — the renderer reads it directly. Images: PNG/JPG/WebP up to 15 MB. Videos: MP4/MOV/WebM up to 200 MB. The same bytes are stored once (content-hashed).

Upload a brand asset (product photo, app screenshot, packaging) into Brand DNA and store it on R2. Pass image_url (https PNG/JPG/WebP) or image_base64.

Two ways to file it:

• Send description (and optionally kind, use_when, tags, name): Siren trusts your words and files the asset as-is. No read.

• Send only the file: Gemini reads the picture and writes name, kind, description, use_when, tags itself. scan_status goes scanning → ready in about 8 seconds; poll list_product_screens.

kind is free text ("product photo", "dashboard screenshot", "packaging"), there is no fixed list. A brief that names an asset ("advertise the pink handbag") pulls that file into the still. screen_type / device / theme only matter for device-framed screenshot masters.