# Flayr — full documentation --- Public documentation snapshot generated for this deployment. Page Markdown is available by appending .md to its URL. --- Source: https://flayr.social/ai-setup # Set up Flayr with your AI Help me set up Flayr, a social media workspace for brands: create drafts, connect social accounts, schedule and publish posts, and read results. Read the full documentation at https://flayr.social/llms-full.txt (index: https://flayr.social/llms.txt). Over MCP, connecting, reading, drafting and publishing need the Pro plan or higher. REST API keys: reading from Pro+, AI generation from Pro+, publishing from Agency+. Queues and approvals need Agency+. Generation uses the plan's Embers; your assistant subscription is separate. Ask me which brand and accounts to connect, then set up Flayr for me. Ask which assistant or MCP client I prefer and what I want it to do. Explain the required Flayr plan before we start. Guide me through https://flayr.social/ai-setup. Ask for only the brand access and scopes needed: read to inspect, write to create drafts, publish only if I want posting or scheduling. Let me complete sign-in and social-account authorization myself. Never ask me to paste passwords or keys into this chat; use OAuth or my client's secret storage. Check the connection and brand before creating a draft. Ask for confirmation before publishing, deleting, or spending money. Over MCP, connecting, reading, drafting and publishing need the Pro plan or higher. REST API keys: reading from Pro+, AI generation from Pro+, publishing from Agency+. Queues and approvals need Agency+. Generation uses the plan's Embers; your assistant subscription is separate. ## Claude desktop or web 1. Open Customize → Connectors (Settings → Connectors in older layouts), then Add custom connector. A workspace owner may need to enable custom connectors. 2. Name it Flayr and enter https://flayr.social/api/mcp/claude. Choose OAuth sign-in, then Connect. 3. Sign in to Flayr, choose your brand and permissions, and allow the connection. Enable Flayr in your conversation and paste the setup prompt. ## ChatGPT 1. Open ChatGPT Plugins, choose +, then Add custom MCP server. In older layouts, enable Developer mode under Settings → Apps → Advanced settings, then create an app. Your workspace may restrict custom apps. 2. Enter Flayr as the name and https://flayr.social/api/mcp/chatgpt as the server URL. Select OAuth authentication. 3. Create the connection and sign in to Flayr. Select the brand and permissions, then enable the connection in a chat and paste the prompt. If custom MCP is unavailable on your account, choose a supported MCP client below. ## Gemini 1. Use Gemini CLI for this MCP setup. This guide does not assume that the Gemini web app offers arbitrary MCP connections. 2. Add the configuration below to ~/.gemini/settings.json, merging it with any existing mcpServers. 3. Start Gemini CLI, run /mcp auth flayr, and complete Flayr sign-in and consent. Paste the setup prompt. ``` { "mcpServers": { "flayr": { "httpUrl": "https://flayr.social/api/mcp" } } } ``` ## Cursor or Claude Code 1. Claude Code: run the command below, then open /mcp and authenticate Flayr. 2. Cursor: merge { "mcpServers": { "flayr": { "url": "https://flayr.social/api/mcp" } } } into ~/.cursor/mcp.json. Open the MCP tools settings and connect Flayr. 3. Complete OAuth sign-in, choose your brand and permissions, then paste the setup prompt into your agent. ``` claude mcp add --transport http flayr https://flayr.social/api/mcp ``` ## Other MCP clients 1. Add a remote Streamable HTTP server at https://flayr.social/api/mcp. 2. Use OAuth if the client supports it. Trigger a tool call to start sign-in; discovering tools alone does not require login. Select your brand and permissions on the consent screen. 3. If OAuth is unsupported, create a key below and store it in your client as the Authorization header: Bearer YOUR_KEY. Paste the setup prompt and ask it to call whoami. ## Plain API key 1. Sign in below, choose the brands and scopes your integration needs, then create a key. Copy it once into your application’s secret store. 2. Send Authorization: Bearer YOUR_KEY to https://flayr.social/api/v2/ping. Check authenticated is true, then list /api/v2/brands and pick the intended brand. 3. Read https://flayr.social/docs for request bodies. A key reaching multiple brands must name brandId on brand-specific requests. Start with a draft; enable publish only when you want posting or scheduling. ``` curl "https://flayr.social/api/v2/ping" -H "Authorization: Bearer $FLAYR_API_KEY" ``` --- Source: https://flayr.social/docs # Flayr API reference # flayr > flayr (flayr.social) creates, schedules and publishes social media posts across Instagram, TikTok, YouTube, LinkedIn, X, Facebook, Threads, Bluesky, Pinterest and more — for one person or many brands. Agents can drive it through a remote MCP server (OAuth sign-in or a flayr API key) or the REST API (API key). ## Documentation - Full documentation (all public help articles, API schemas and complete MCP tool descriptions): https://flayr.social/llms-full.txt - AI setup prompt and client paths: https://flayr.social/ai-setup - Markdown: append .md to a help article or docs URL, for example https://flayr.social/docs.md. ## Authentication - Create an API key at https://flayr.social/developers. Send it as `Authorization: Bearer flayr_sk_…`. - Scopes: `read` (GET), `write` (create/edit drafts, media, formats, experiments), `publish` (post, schedule, posting queues, credit rules), `review` (approve held posts; never implied). `admin` = every scope except `review`. - A key may be bound to one brand: it then only sees and posts to that brand. - Creating a brand (POST /api/v2/brands, MCP create_brand) needs an account-wide key with `write`; a brand-bound key gets 403, and the plan's brand limit answers 402. The same key reaches the new brand straight away. - Plans (REST): API from Pro+; publishing and posting queues from Agency+ (the Agency plan includes everything). - Plans (MCP): Over MCP, connecting, reading, drafting and publishing need the Pro plan or higher. Publishing counts against the plan's direct posts, with the plan's rate limits, monthly API quota and Ember charges; posting queues, reviews and approvals need Agency+. ## MCP server - Endpoint: https://flayr.social/api/mcp (Streamable HTTP, stateless). Every tool runs the matching /api/v2 endpoint with your key, so scopes, plan gates, brand binding, rate limits and quotas are the REST API's. - Sign in with OAuth (no key to paste): add https://flayr.social/api/mcp as a remote MCP server in any client that supports MCP OAuth (Claude Code, other clients). Store builds: Claude connectors use https://flayr.social/api/mcp/claude, ChatGPT apps use https://flayr.social/api/mcp/chatgpt. It signs you in to flayr (the client asks only for standard scopes: openid profile email offline_access), then flayr's consent screen asks which brand the app may use and what it may do there: read, write and/or publish (read + write are ticked by default; publish is opt-in; approving reviews is never granted to an app). Remove a connected app any time in Settings › Integrations › Connected agents. - Setup guide for people (Claude, ChatGPT, Claude Code): https://flayr.social/docs/ai-assistants - Claude Code: `claude mcp add --transport http flayr https://flayr.social/api/mcp` (OAuth), or with a key: `claude mcp add --transport http flayr https://flayr.social/api/mcp --header "Authorization: Bearer flayr_sk_…"` - Any MCP client: { "type": "http", "url": "https://flayr.social/api/mcp", "headers": { "Authorization": "Bearer flayr_sk_…" } } - Flow: whoami → list_brands → upload_media (local file) → create_content (draft; nothing posts) → publish with contentId and an idempotencyKey (or add_queue_items) → get_content for live URLs. - Tools that PUBLISH or are DESTRUCTIVE act on real accounts: confirm with the user first. - No sign-in needed to connect and look: initialize, ping and tools/list answer without a key or token. tools/call needs one (401 + WWW-Authenticate pointing at the OAuth metadata). ### Tools - media_qa_get (read-only): Reads the cached video/audio QA report, timestamped findings and approval/booking gate. - media_qa_rerun (writes flayr data, `write` scope): Queues a free media QA run using the existing per-minute cap. - whoami (read-only): Returns who this connection (an OAuth sign-in or an API key) belongs to: userId, the account's current plan tier, and brandId/brandName when the connection is bound to one brand (null = account-wide). - invite_brand_viewer (writes flayr data, `write` scope): Invites an external client to view one brand (client project), without joining the agency organization or seeing sibling brands. - list_brands (read-only): Lists the brands this connection can file content into and publish through. - create_brand (writes flayr data, `write` scope): Creates a new brand in the account owner's organization, the same as "New brand" in the dashboard. - brand_profile_get (read-only): A brand's profile (website, companyName, tagline, industry, audience, values, pillars, hashtag sets), its default voice, colors and fonts. - brand_profile_update (writes flayr data, `write` scope): Fills in a brand's profile — e.g. - list_connected_accounts (read-only): The social accounts a brand can post to — the same set publish would use for that `brandId`: platform, handle, display name, health (healthy, needs_reauth, disconnected), whether it is the brand's default for its platform (`isDefault`) and whether flayr can post there right now (`postable`; Reddit is paused because Reddit closed its API to third-party apps). - account_refresh (writes flayr data, `write` scope): Re-reads a connected account's handle, display name and avatar from the network (use after the user renames the account) and returns the stored values. - account_remove (DESTRUCTIVE): DESTRUCTIVE: removes ONE dead connection (by account id) from the brand, leaving the brand's other accounts on that platform alone. - account_reconnect (writes flayr data, `write` scope): Returns `authUrl`, the link the user opens (signed in to flayr, with this brand selected) to re-authorise an account that list_connected_accounts shows as needs_reauth or disconnected. - account_set_default (writes flayr data, `write` scope): Sets the brand's default account for one platform (where posts on that platform go when no account is named), or clears it with accountId null. - get_dm_entry_points (read-only): What a connected Instagram account or Facebook Page (id from list_connected_accounts) shows when someone opens a DM: ice breaker questions, and on Facebook also the greeting, Get Started button and menu links. - set_dm_entry_points (PUBLISHES to social accounts, `publish` scope): Changes what EVERY visitor sees when they open a DM with the account; only the fields you pass change, null or [] removes one. - clear_dm_entry_points (DESTRUCTIVE): DESTRUCTIVE: removes the ice breakers, and on Facebook also the greeting, menu and Get Started button, from the account; every visitor stops seeing them. - list_youtube_playlists (read-only): Playlists of the YouTube channel(s) a brand publishes to. - list_pinterest_boards (read-only): Boards of the Pinterest account(s) a brand publishes to. - suggest_tags (read-only): Hashtag and @mention suggestions for each platform, from the brand's own config: hashtags from its brand profile's hashtag sets (within each platform's limit, skipping ones already in `text`), mentions from its mention contacts written the way each network receives them (`@handle`; on LinkedIn `@[Name](urn:li:organization:…)`). - upload_media (writes flayr data, `write` scope): Step 1 of attaching a LOCAL file (video, image or audio) to a draft. - list_content (read-only): Lists content items (drafts), newest first, one page at a time: each item is a summary (id, title, type, durationMs, createdAt, postState "posted" / "scheduled" / null). - get_content (read-only): One content item plus its live posting status: `postState` and `posts[]` (up to 20, newest first) with each post's status (scheduled · publishing · published · partial · failed · review_held · held), scheduledAt, and per-platform status, live URL and error. - create_content (writes flayr data, `write` scope): Creates a DRAFT content item. - edit_post_labels (writes flayr data, `write` scope): Sets internal post labels and per-platform/account instanceLabels. - update_content (writes flayr data, `write` scope): Edits a draft in place; only the fields you pass change. - labels_bulk_edit (writes flayr data, `write` scope): Adds and/or removes labels on up to 100 content items in one call: each item becomes (labels − remove) + add. - archive_content (writes flayr data, `write` scope): Soft-archives an uncommitted draft or failed generation. - delete_content (DESTRUCTIVE): DESTRUCTIVE: permanently deletes a content item from the library. - combine_clips (writes flayr data, `write` scope): Extends a video draft (`id`) with more clips and image cards into ONE finished video, rendered by flayr and saved as a NEW linked draft (same brand, caption copied, credits merged, labelled variant:combined). - list_studio_cuts (read-only): Saved versions (drafts and final cuts) of a Long-form Studio project (`id`), newest first, and THE final cut: the one campaigns and approvals use, with its rendered draft (`contentId`). - save_studio_cut (writes flayr data, `write` scope): `action: "save_draft"` stores the edit as it stands as a named version; free, nothing renders. - get_job_status (read-only): Status of an async job (combine_clips, render_motion_ad, or an API video generation): pending, processing, completed or failed. - render_motion_ad (writes flayr data, `write` scope): Turns one Library image (the card) into a 6-15 s motion ad: hook (push-in on the card), up to 3 body beats (pans with the text), then a CTA end card in the brand color with the CTA and the link host. - list_brand_segments (read-only): A brand's segments: one per confirmed offer that names an audience, with its pains, outcomes, proof and the brand website (the default CTA link), ranked shops/commerce first and local services second (each has `tier` and `rank`). - generate_segment_ad (writes flayr data, `write` scope): Builds a segment's ad script as beats (hook, persona, offer, proof, CTA) from the owner's own words, or checks the `beats` you edited. - voice_segment_ad (writes flayr data, `write` scope): Speaks a segment ad's script over the silent draft generate_segment_ad rendered (`contentId` = its resultContentId; pass the same `segmentId` and edited `beats`). - plan_teardown (read-only): Teardown Studio: send a 3D model (`model`, base64 STL, 3MF or GLB, up to 3 MB inline) and get its parts list, a default teardown/1 plan (hold, explode, label the biggest parts, slow-motion, reassemble, reveal, brand end card; 16:9 and 9:16) built from part count and bounding boxes, and the render estimate (frames, worker time; free). - ad_cut_lint (writes flayr data, `write` scope): Checks an ad's cut against the ad-cut rules: too many joins (warning), joins only at a rest point, no cut inside a caption or its fade, one caption layer, no audio dip at a join, exactly one ending, and the network's length / aspect / ad-text window (TikTok 9:16, 12-25 s, ad text up to 100 by default). - video_studio_auto_run (writes flayr data, `write` scope): Long-form Video Studio project `id`: with no `action` it runs the brand's enabled auto steps (dead-air trims at sentence boundaries, retake picks, dissolves, room tone, loudness, presets) and writes suggestion items for the timeline. - video_studio_auto_suggestions (read-only): The auto-edit suggestions for Video Studio project `id` (step, kind, status, where on the timeline, a plain summary, the payload), the latest run (which steps ran or were skipped and why) and the brand's auto profile. - publish (PUBLISHES to social accounts, `publish` scope): PUBLISHES TO REAL SOCIAL ACCOUNTS. - get_post (read-only): A post (`id` = convexPostId from publish, or posts[].id from get_content): status, slot, platforms, its internal labels and per-platform/account instanceLabels, and while it is scheduled the first comment each platform will publish and whether it can be changed now. - update_scheduled_post (PUBLISHES to social accounts, `publish` scope): CHANGES WHAT A SCHEDULED POST WILL PUBLISH on real accounts, keeping its slot, accounts, options, labels and draft. - reschedule_post (PUBLISHES to social accounts, `publish` scope): MOVES A SCHEDULED POST to `scheduledAt` (ISO 8601 with a timezone, e.g. - cancel_scheduled_post (PUBLISHES to social accounts, `publish` scope): Takes a SCHEDULED post off the platform schedule and marks it cancelled (the draft stays, so it can be published again). - list_reviews (read-only): Scheduled posts waiting for (or given) a human sign-off, oldest slot first. - decide_review (PUBLISHES to social accounts, `publish` scope): decision "approve" sends a held post to the platform for its slot (GOES LIVE) — needs the explicit `review` scope (admin does not include it) and never works on a post the same connection created. - bulk_decide_reviews (DESTRUCTIVE): Discard or hold 1–100 scheduled-post reviews in one call. - move_reviews (writes flayr data, `write` scope): Moves one or many posts held for review ("move to Tuesday 10:00", "+1 day"). - move_approvals (writes flayr data, `write` scope): Moves the planned time of one or many items waiting for approval. - switch_post_accounts (PUBLISHES to social accounts, `publish` scope): Re-points platform legs of one post to another healthy connected account of the same brand and platform, e.g. - list_failed (read-only): The Schedule → Failed backlog of the brand: one row per platform of a post that did not go out, with its row `id`, postId, contentId, account, slot, lastError, reasonClass and `coverage` ("live" / "rebooked" when the platform is now covered elsewhere, null when nothing known covers it). - dismiss_failed (writes flayr data, `write` scope): Dismisses rows of the Failed backlog by the ids list_failed returned (up to the batch limit per call), like the dashboard's Dismiss. - approvals_list (read-only): The approvals inbox: everything that waits on the user's decision, in one list. - approvals_decide (PUBLISHES to social accounts, `publish` scope): Decides ONE item from approvals_list (`id`): decision "approve" or "reject", optional `note`. - list_approvals (read-only): Content held for approval that waits on the account owner's decision, newest first: posts filed with publish `requiresApproval: true`, drafts submitted for review, and workflow runs parked at an approval gate. - decide_approval (PUBLISHES to social accounts, `publish` scope): Same rules as the dashboard: the assigned approver, or an owner/admin of the org, may decide. - list_approval_groups (read-only): The same held content as list_approvals, grouped by piece: the variants of one draft (or sharing a `group:` label), with the axes they vary on (theme, hook, audio …), a tally (approved / redo / dropped / open) and each variant's state and slot time. - decide_approval_group (PUBLISHES to social accounts, `publish` scope): Decides several variants of a group from list_approval_groups at once, each as decide_approval would: `members` "all" (open variants), an array of approvalIds, or {axis: value} (e.g. - list_queues (read-only): Posting (drip) queues of one brand. - get_queue (read-only): A queue and its items in order, with each item's state (queued · publishing · scheduled · posted · failed · skipped), booked or projected slot, and attribution status. - create_queue (PUBLISHES to social accounts, `publish` scope): Creates a posting queue. - update_queue (PUBLISHES to social accounts, `publish` scope): `status: "paused"` stops new bookings (already-booked posts stay booked); "active" resumes. - delete_queue (DESTRUCTIVE): DESTRUCTIVE: deletes the queue (its drafts stay in the library). - add_queue_items (PUBLISHES to social accounts, `publish` scope): Appends drafts (content ids) to the end of a queue — they will be BOOKED AND POSTED on the queue's schedule. - queue_item_action (PUBLISHES to social accounts, `publish` scope): `action`: "skip" passes over a queued item; "retry" puts a failed/skipped item back in line; "unschedule" deletes a booked platform post and puts the item back in line. - remove_queue_item (DESTRUCTIVE): DESTRUCTIVE: removes an item (the draft stays in the library). - reorder_queue_items (PUBLISHES to social accounts, `publish` scope): Send every waiting (queued) item id exactly once, in the new order. - get_analytics (read-only): Engagement overview for the last 7, 30 or 90 days. - compare_post_instances (read-only): Per-account metrics and tag, campaign, experiment and series roll-ups. - query_insights (read-only): Read-only analytics query: one `metric` aggregated (median by default) over posts, broken down by up to a few dimensions (platform, weekday, hour, brand, campaign, postType, label:, arm), at a fixed post age `window` (48h / 7d / 30d / lifetime) so posts are compared fairly. - compare_labels (read-only): Splits every labelled post by the values of one label key (e.g. - list_experiments (read-only): A/B experiments. - get_experiment (read-only): One experiment: hypothesis, variants, compareKey, window and status. - create_experiment (writes flayr data, `write` scope): Creates an A/B experiment. - update_experiment (writes flayr data, `write` scope): Changes an experiment's fields (e.g. - delete_experiment (DESTRUCTIVE): DESTRUCTIVE: deletes the experiment record (content keeps its labels). - get_experiment_results (read-only): The experiment's posts split by its compareKey, with the leading variant by its primary metric and n per arm, plus `overlay`: one line per variant (primary metric to date; align=armDay lines arms up from their first post; null = not reported). - get_experiment_readout (read-only): n per arm, pooled reach engagement rate (or average percentage watched when selected), a 90% interval and a hedged verdict (likely_winner, no_clear_winner or not_enough_data). - get_experiment_rounds (read-only): A version test's rounds: each closed round's frozen snapshot, the open round's live numbers (null = not reported), the winner if one was recorded, and any repeat-winner proposal. - start_experiment_round (writes flayr data, `write` scope): Files the round's versions into the approval queue on the given platforms, in spaced slots with UTM links. - close_experiment_round (writes flayr data, `write` scope): Freezes the open round's numbers and keeps the best arms for the next round. - propose_repeat_winner (writes flayr data, `write` scope): Proposes slots to post the winning version again (default 3 over 2 weeks). - list_text_templates (read-only): Reusable text shapes per brand: sections, length targets, hook patterns, CTA slots and guardrails. - get_text_template (read-only): One format (text template) with its full structure and example. - create_text_template (writes flayr data, `write` scope): Creates a reusable format (text template) in a brand. - update_text_template (writes flayr data, `write` scope): Changes a format; only the fields you pass change. - delete_text_template (DESTRUCTIVE): DESTRUCTIVE: deletes a format (drafts started from it keep their text). - list_attribution_rules (read-only): The brand's "posts like this must carry a credit" rules and its mode (flag / push_down). - list_rotations (read-only): List a brand’s rotation definitions. - create_rotation (PUBLISHES to social accounts, `publish` scope): Brand admins configure hooks, source media, captions, cadence and networks. - update_rotation (PUBLISHES to social accounts, `publish` scope): Patch editable rotation config. - list_share_rules (read-only): The brand's share rules: "when publishes, reshare to (or comment on it) after N minutes with text T", each with its approval mode. - create_share_rule (PUBLISHES to social accounts, `publish` scope): Creates a rule that reshares (or comments on) every new post of the source accounts. - list_publish_actions (read-only): Pending, sent and failed comments-after-publish and reshares of the brand (filter by `status`, e.g. - act_on_publish_action (PUBLISHES to social accounts, `publish` scope): approve lets a rule's reshare / comment go out at its time; retry re-sends a failed one (same idempotency key); reject / cancel stop it. - add_post_comments (PUBLISHES to social accounts, `publish` scope): Schedules comments on a post, sent once after it is live on that platform and its tokens resolve ({{postUrl}}, {{parentPostUrl:}}, {{youtubeUrl:}}), optionally at sendAt. - list_post_comments (read-only): A post's comments-after-publish and reshares, with status (waiting, needs_approval, sent, failed) and the resolved text. - list_frames (read-only): The brand's frames (borders, overlays, lower thirds, corner tags, quote-card frames, ribbons) plus the built-in flayr frames in the brand colors. - get_frame (read-only): One library frame with its sizes and content areas. - create_frame (writes flayr data, `write` scope): Copy a flayr frame into the brand library (`defaultKey`, optional colors/texts), or add uploaded PNG/SVG art (upload_media first; `variants` of storageIds, the content area is detected from transparency). - apply_frame (writes flayr data, `write` scope): Draws a frame over an image and returns a new image URL (the original is untouched). - get_frame_settings (read-only): Which frame each platform's images get automatically when a post is published or scheduled. - update_frame_settings (writes flayr data, `write` scope): Frame every image posted to a platform automatically (frameRef), or stop (frameRef null). - import_frames (writes flayr data, `write` scope): flayr admins only: load a frame pack into a brand under one batchId (up to 25 frames per call). - offers_capture (writes flayr data, `write` scope): Turns what the brand sells (pasted text, or answers to the offer interview) into draft offers in its offer bank, with prices from the plan catalog, Shopify or the text. - offers_list (read-only): The brand's offer bank (filter by status: draft, confirmed, retired). - offers_update (writes flayr data, `write` scope): Edits an offer's fields or status; "confirmed" makes it usable for hooks and CTAs. - hooks_generate (writes flayr data, `write` scope): Writes a batch of draft hooks (on-screen card + spoken line) from the confirmed offers, claims-checked; blocked ones come back in `dropped`, unsaved. - hooks_list (read-only): The brand's hook bank (filter by status: draft, approved, retired), with each hook's claims result. - hooks_update (writes flayr data, `write` scope): Edits a hook or sets its status. - bodies_map (writes flayr data, `write` scope): Maps library clips, Shopify products, features or texts to draft bodies (what each shows and proves) so hooks can lead into them. - ctas_generate (writes flayr data, `write` scope): Writes a batch of draft calls to action for the confirmed offers, claims-checked against where they point. - ctas_list (read-only): The brand's CTA bank (filter by status: draft, approved, retired), with each CTA's goal (goalKey, isPrimary, paidEligible, adButton) and claims result. - ctas_create (writes flayr data, `write` scope): Adds a call to action written by the person, claims-checked, optionally tagged as a goal (goalKey; isPrimary makes it the brand's primary goal and demotes the previous one). - ctas_update (writes flayr data, `write` scope): Edits a CTA, its status or its goal fields (goalKey, isPrimary, paidEligible, adButton). - cta_settings_get (read-only): The brand's goals (source tagged, implicit from the website, or none; the primary goal) and its CTA check settings (ctaLevel, ctaPaidLevel, organicSupportingHosts, autoApplyPrimaryCta). - cta_settings_update (writes flayr data, `write` scope): Changes only the CTA check settings sent: ctaLevel (off, warn, block), ctaPaidLevel (warn or block), organicSupportingHosts and autoApplyPrimaryCta. - claims_check (read-only): Checks a hook, CTA, caption or ad against the brand's claims sources (verified prices, banned phrases, competitors, destinations). - cta_check (read-only): Checks whether a draft, post or link points at the brand's goal page (the same check the ad and boost routes run in paid mode; a block there refuses the ad). - get_signup_sources (read-only): Sign-ups, first posts and paid conversions per sign-up source (paid:, organic, outreach, friends_family, internal, unknown), with the total net of friends/outreach/internal, and per ad campaign, ad content, ad set (utm_term) and landing path, including the campaign x landing grid (optional campaign prefix filter, e.g. - list_growth_triggers (read-only): The brand's keyword triggers: a comment matching a keyword gets a public reply and/or a DM. - get_growth_trigger (read-only): One trigger with its keywords, texts, link, cap and counts. - get_growth_trigger_stats (read-only): Matched comments, unique commenters, replies, DMs and failures, in total and per day. - create_growth_trigger (writes flayr data, `write` scope): Creates a keyword trigger, always INACTIVE: nothing is sent until a person turns it on. - update_growth_trigger (PUBLISHES to social accounts, `publish` scope): Changes a trigger; only the fields you pass change. - delete_growth_trigger (DESTRUCTIVE): DESTRUCTIVE: deletes a trigger (its logs stay). - ads_offers_list (read-only): The brand's new-advertiser offers per ad network, one row per ad account (or a network not connected yet): status, spend so far, what is left to spend, the daily pace and the deadline, and how to claim. - ads_offer_update (writes flayr data, `write` scope): Records the claim of one offer row (`claimId` = a row id from ads_offers_list): status, the date it was claimed, and notes. - lead_booking_slots (read-only): The next free times on the brand's connected Google or Microsoft calendar for a call with one lead, under the brand's booking rules (length, buffers, hours). - lead_book_call (writes flayr data, `write` scope): Sends the lead a calendar invite with a Meet or Teams link at a free slot from lead_booking_slots, and marks the lead booked. - ads_site_tags_get (read-only): flayr.social's ad tags per network (reddit, tiktok, linkedin, x, google, pinterest, snapchat): saved id, env default, requested, effectively on. - ads_site_tag_set (writes flayr data, `write` scope): Sets ONE network's tag on flayr.social (network, id, enabled, conversion references). - ads_tiktok_pixels_list (read-only): The TikTok pixels on the brand's selected TikTok ad account: numeric id (for campaign optimization), pixel code (siteTagId, for the site), status, last fired. - ads_tiktok_pixel_ensure (writes flayr data, `write` scope): Reuses the TikTok pixel named "flayr.social" (or name / tagId) on the selected TikTok ad account, or creates it when none matches (audited), then saves its pixel code as the site's TikTok tag (save, default true; enable to turn it on). - ads_page_get (read-only): The Facebook Page the brand's Meta ads run as (pageId, name, status: active / needs_reconnect / not_connected) and the candidates: the brand's own connected Facebook accounts. - ads_page_set (writes flayr data, `write` scope): Picks the Facebook Page the brand's Meta ads run as, from the brand's ALREADY connected Facebook accounts (ads_page_get lists them); pageId null clears it. - brand_business_details_get (read-only): A brand's legal name, registered address, website, currency and timezone: what ad networks ask for when you open an ads account. - brand_business_details_update (writes flayr data, `write` scope): Sets a brand's legal name, registered address, currency (ISO, like USD) and/or timezone (IANA, like America/New_York). - brand_mailbox_get (read-only): Whether the brand sends lead follow-ups from its own mailbox: the address, provider, status, daily send cap (limit, remaining, reset), the fallback when it cannot send (resend = flayr's sender, hold = do not send) and open/link tracking. - brand_mailbox_connect_link (writes flayr data, `write` scope): A one-time link that connects the business's own Gmail, Microsoft or IMAP mailbox to the brand. - brand_mailbox_send_test (writes flayr data, `write` scope): Sends one test email from the brand's connected mailbox to your own account address. - brand_mailbox_contact_thread (read-only): One contact's email with the brand: the threads in the brand's real mailbox, plus what flayr sent them from it with opens, clicks, bounces and the latest reply. - brand_sending_identity_get (read-only): Who the brand's lead follow-up email comes from: mode flayr (" via flayr"), domain (the brand's own domain, only once verified) or mailbox (its connected mailbox); the reply-to; the domain's DNS records, status, warm-up and bounce health; and a preview of each From line. - brand_sending_identity_set (writes flayr data, `write` scope): Choose `mode` (flayr, domain or mailbox), the display `fromName`, `replyTo`, `repliesTo` (brand or flayr) and `fromLocalPart` (before the @ on the brand domain). - brand_sending_domain_add (writes flayr data, `write` scope): Registers the brand's `domain` (e.g. - brand_sending_domain_verify (writes flayr data, `write` scope): Asks the email provider to check the domain's DNS records now and returns the status (pending while DNS propagates, verified when ready). - brand_sending_domain_remove (DESTRUCTIVE): Removes the brand's sending domain. - brand_sending_identity_send_test (writes flayr data, `write` scope): Sends one test email to your own account address with the brand's current identity and reports the From actually used (`via` mailbox or resend; a domain that is not verified yet shows the flayr address). - ads_campaigns_import (writes flayr data, `write` scope): Import one resumable page of prior campaigns, ad sets, ads and available daily results from the selected connected ad account. - ads_campaign_import_status (read-only): Read the selected account import state, cursor, counts, result window and partial hierarchy warning in the active brand. - ads_snapshot_collect (writes flayr data, `write` scope): Save an immutable, org and brand scoped snapshot for selected ad accounts and an inclusive 1–30 day window. - ads_snapshots_get (read-only): Read one saved ads data snapshot by id, or recent snapshot headers for the active brand. - ads_deep_dive_quote (read-only): The Embers price of a deep dive on a saved snapshot, and whether a recent run makes it free. - ads_deep_dive_run (writes flayr data, `write` scope): Run a deep dive on a saved snapshot and save the report. - ads_deep_dive_get (read-only): One saved deep dive by id, as json or an export (markdown, csv, pdf) of the stored report. - ads_deep_dive_compare (read-only): Compare an older and a newer saved run: each finding is new, resolved, worse, better or unchanged, with metric deltas. - ads_checkpoints_get (read-only): Scheduled check-ins for one campaign (default day 3, 7 and 14 after activation): whether they are on, the Embers price of each, and every past check-in with its spend, findings and charge. - ads_checkpoints_set (writes flayr data, `write` scope): Switch scheduled check-ins on or off for one campaign (owner or admin only). - ads_learned_insights (read-only): The insights library: finished experiments and deep-dive verdicts confirmed across runs (worked / did not work), each deep-dive one with its evidence and report link. - ads_boost_candidates (read-only): The brand's published posts ranked for a boost (reach, engagement rate, link clicks, recency and timeliness), with window/windowLabel (Boost now or Upcoming), separate missedWindows for expired posts that cannot be boosted, upcomingDates from the shared season config, score parts, the call-to-action link found, and whether an ad account is connected for the network. - ads_auto_judge (read-only): The brand's scheduled auto-judge: its settings (off by default) and recent proposal groups, one per run. - ads_lead_replies_get (read-only): The brand's lead response rule for click-to-message ads: whether a person who types to the ad gets an automatic first reply in the same Messenger/Instagram DM thread (off by default), its text ({{name}} = first name; null = the greeting), the platform window in hours, and up to 20 recent leads with when they were answered. - ads_lead_replies_set (writes flayr data, `write` scope): Switches the automatic first DM reply for messaging-ad leads on or off (firstReplyEnabled) and sets its text (firstReplyText, up to 600 characters; null uses the greeting; omit to keep it). - ads_launch_review (read-only): Every paused campaign of the brand on every network, with each ad's text, headline, button and destination, and the pre-launch checks (destination resolves, UTM tags, button, end date or lifetime budget, max spend, call to action, same destination across networks), each pass, warn or fail. - ads_page_layout (read-only): The /ads page's tabs (Insights, Campaigns, Ads, Leads, Setup, Pending, Custom), each tab's sections, who sees each (boost = Pro and up, manage = Premium and up, advanced = Advanced nav mode only), and the API v2 path and MCP tool that return each section's data. - get_ads_command_center_config (read-only): flayr admins only: the businesses the Ads command center reports on (funnel steps, primary conversion, pinned ad accounts, sources, enabled), the alert rules and the rollup window. - get_ads_history_backfills (read-only): flayr admins only: per selected Meta ad account, the history import that brings in campaigns that ran before the account was connected: status, date range, progress and row counters. - ads_accounts_list (read-only): The brand's ad account with its currency, spend limit, balance (minor units) and readiness. - ads_campaigns_list (read-only): The brand's ad campaigns with status, budget, start/end dates, max spend, spend to date, ad sets and ads. - ads_campaign_get (read-only): One ad campaign by its Flayr id, with its ad sets and ads, including each ad's network review status, reason when available, and last sync time. - ads_insights (read-only): Impressions, clicks, spend, link clicks and leads per campaign for a date range (default the last 30 days, at most 93), with totals per currency. - ads_readiness (read-only): Whether each connected network and ad account can run ads, and what to fix first. - ads_campaign_pause (writes flayr data, `write` scope): Pauses a live ad campaign on its ad network so it stops spending (`action: "pause"` or `"stop"`; both leave it paused). - ads_delete_campaign (DESTRUCTIVE): DESTRUCTIVE: permanently deletes an ad campaign in flayr and on its ad network. - ads_import_preview (read-only): What an Ads Manager export (CSV text, or a base64 .xlsx) would import, without writing: the column mapping found, columns left unmapped, the first rows, malformed rows by line number, and each conflict with a synced row (the synced value is kept). - ads_import_commit (writes flayr data, `write` scope): Import the rows of an Ads Manager export as imported reporting rows, in one batch that ads_import_undo takes back. - ads_import_list (read-only): The workspace's stats file imports, newest first: file, network, date range, row counts, and whether each was undone. - ads_import_get (read-only): One import by id: the campaigns, ad sets and ads it brought in with their totals. - ads_import_undo (writes flayr data, `write` scope): Take one import back: rows it created are removed and metrics it filled on synced rows are cleared. - ads_caps_get (read-only): The brand's activation spend caps and what is committed against them this month, the owner's agent ceilings, and the ad account spending limit with what is left of it (all in cents). - ads_caps_set (writes flayr data, `write` scope): Sets the brand's monthly and/or per-campaign activation caps, in cents (e.g. - ads_account_spend_limit_set (writes flayr data, `write` scope): Sets the Meta ad account spending limit, in the account currency (e.g. - ads_ad_set_placements (writes flayr data, `write` scope): Changes where an existing ad set runs. - ads_ad_set_dataset (writes flayr data, `write` scope): Attaches a Meta dataset (pixel) to an existing ad set, optionally with the conversion event (e.g. - ads_campaign_approve (writes flayr data, `write` scope): Approves a proposed ad campaign (ads:manage or ads:activate). - ads_campaign_scale (writes flayr data, `write` scope): Changes a campaign's campaign-level budget to budgetMinor (whole cents, e.g. - ads_lead_forms_list (read-only): The Meta Instant Forms (lead forms) on the brand's selected ad account: id, name, status. - ads_lead_form_create (writes flayr data, `write` scope): Creates a Meta Instant Form on the brand's selected ad account: name, privacyPolicyUrl (https), questions (Meta question objects, e.g. - ads_lead_form_consent_get (read-only): The brand's saved lead consent (text, version, title, checkboxLabel), whether leads are stored (enabled) and emailed (followUpEnabled), the code defaults, and the forms already created with the consent checkbox. - ads_lead_form_consent_set (writes flayr data, `write` scope): Saves the brand's lead consent: consentText, consentVersion (a new version is required when the wording changes), consentTitle, consentCheckboxLabel, and the switches enabled (store leads) and followUpEnabled (email leads who ticked consent; needs enabled). - ads_lead_form_consent_copy (writes flayr data, `write` scope): Copies a live Meta Instant Form (copyFromFormId) into a new form with the same questions, pages and privacy link, plus the brand's saved consent checkbox (save it first with ads_lead_form_consent_set). - ads_lead_form_swap_ad (writes flayr data, `write` scope): Points a live Meta lead ad (adId) at another Instant Form (newFormId) without Ads Manager: creates a new ad PAUSED in the same ad set with the same copy and media and the new form, switches it on, and only then pauses the old ad. - ads_audiences_list (read-only): The brand's Meta custom and lookalike audiences (id, name, type, preset, size) and the owner's audience limits (presets on, most included / excluded per ad set, lookalike ratio range, customer-list batch size). - ads_audience_create (writes flayr data, `write` scope): Creates a Meta custom audience on the brand's selected ad account from a preset: site_visitors (the brand's Meta pixel visitors), signup_page_visitors (pixel visits to the sign-up page; urlContains overrides the configured path), trial_starters (people who fired the trial event), customer_list (empty; fill it with ads_audience_users_add) or lookalike (seedAudienceId from ads_audiences_list, country, ratio). - ads_audience_users_add (writes flayr data, `write` scope): Adds people to a customer_list audience (audienceId from ads_audiences_list or ads_audience_create): users is a list of { email?, phone? - ads_targeting_search (read-only): Searches the brand's selected ad account for targeting ids by name: q (2+ characters), dimension (default interest; also behavior, demographic, geo with geoType and countryCode), limit. - ads_campaign_create (writes flayr data, `write` scope): Creates a Meta Instant Form lead campaign (goal lead_generation, the ad set's leadGenFormId from ads_lead_forms_list, placements without Audience Network, the age range and countries in targeting) with one image ad, or video ads, created PAUSED. - ads_boost_create (writes flayr data, `write` scope): Boosts a post the brand has already published on X, as published, through the brand's selected X Ads account. - ads_conversion_test_event (writes flayr data, `write` scope): Sends ONE server-side CompleteRegistration to a Meta pixel on the brand's selected ad account with Meta's test code (testEventCode, from Events Manager → the dataset → Test events; required), to prove the Conversions API path delivers. - ads_agent_activity (read-only): Recent agent actions on ads (agent name, reason, outcome), owner approval requests still pending, and the owner's agent ceilings. - get_campaign_review (read-only): A campaign's pieces grouped into review sections (episode, week, channel set, variant group or the creator's own). - group_campaign_review (writes flayr data, `write` scope): Puts the campaign's not-yet-sectioned pieces into review sections (groupBy: week, channel_set, variant_group, episode or phase; default the brand's setting). - decide_campaign_review_section (PUBLISHES to social accounts, `publish` scope): action "approve" approves the section's pending pieces (or pieceIds) and their held posts GO LIVE at their slots — needs the explicit `review` scope (admin does not include it); QA-failed pieces are skipped unless overrideQa. - list_campaign_analytics (read-only): Running, planned and recently finished campaigns (organic, paid or mixed), each with dates, status, posts published of planned, reach, impressions, engagements, link clicks, and for paid spend and cost per result, the goal with its success measure (`success`), plus a daily impressions trend and `overlay` (success measure and reach to date by day of campaign, to overlay campaigns by date or by campaign day). - get_campaign_analytics (read-only): One campaign's full picture: reach and engagement over time, per network, best and worst posts, and for paid the split by ad (with reach) and best/worst ads. - compare_campaigns (read-only): Two or more campaigns side by side (`ids` comma-separated, e.g. - get_post_analytics (read-only): Every metric the networks report for one published post: reach, impressions, plays, average watch time, watch-through, likes, comments, shares, saves, profile visits, follows and link clicks, per network and in total. - get_video_explorer (read-only): Every video and reel the brand published in a timeframe (`days`, snapped to 7, 30, 90 or 365 by default), one point per network: length, watch-through, reach, average watch time, engagement rate, hook retention and end retention. - compare_videos (read-only): Retention curves of two or more videos, from point ids returned by get_video_explorer (`postId:platform`, comma-separated in `ids`). - get_post_siblings (read-only): For one post: the same video posted again on other networks or days, and other variants of the same piece (`variant-of:`, `experiment:`, `ab:` and `hook-template:` labels), each with its per-network video numbers. - estimate_campaign (read-only): Plans a campaign arc from a brief (goal, dates, offer, products or source "brand" with the optional interview, platforms): every post slot with its phase and time, and the most Embers generating its drafts can cost. - create_campaign_brief (writes flayr data, `write` scope): Creates a draft organic-social campaign and its brief in the brand — from its products, or with source "brand" from the brand, its Library and the optional interview (no store needed) — and returns the planned slots and the generation estimate. - generate_campaign_drafts (writes flayr data, `write` scope): Starts writing a draft post for every slot of a builder campaign that has none yet. - book_campaign (PUBLISHES to social accounts, `publish` scope): Books every generated draft of a builder campaign into the campaign's own posting queue, each pinned to its slot time — the posts GO LIVE on the platforms at those times unless the brief requires review. - create_campaign_share (writes flayr data, `write` scope): Makes a PUBLIC review link for a campaign: a page, open to anyone who holds the link with no login, that shows the brand's drafts carrying `campaignLabel` (e.g. - list_campaign_shares (read-only): The review links of a brand, newest first: id, title, label, whether each is still active, when it expires and when it was last opened; plus `expiryDays`, the choices create_campaign_share accepts. - get_campaign_share_verdicts (read-only): What the reviewer said through a review link, draft by draft: `decision` (approve, changes or deny), their comment and name. - revoke_campaign_share (DESTRUCTIVE): DESTRUCTIVE: the public review link stops working at once and cannot be turned back on (make a new link instead). - pronunciations_list (read-only): How every flayr voice (chat voice, voiceovers, character VO) says a brand's words: `pronunciations` (term → sayAs respelling, with `verified` when a Verify passed), `suggested` (learned suggestions, inert until accepted) and `builtIn` entries. - pronunciations_upsert (writes flayr data, `write` scope): Sets how voices say `term` for a brand: `sayAs` is a plain respelling (e.g. - pronunciations_verify (writes flayr data, `write` scope): Speaks a carrier sentence with the entry in a voice (default Gemini Puck), transcribes it, and passes when the transcript has the term or an accepted hearing. - pronunciations_improve (writes flayr data, `write` scope): Runs one improve round: 3+ deliberately different samples of the entry, each with its respelling, script, transcript, word diff and accent check (`accent`, default en-US). - pronunciations_improve_choose (writes flayr data, `write` scope): Saves the chosen sample's respelling on the entry (verified when that sample passed its transcript check) and ends the improve session. - pronunciations_improve_give_up (writes flayr data, `write` scope): Ends an improve session without changing the entry. - list_voices (read-only): Your ready voice clones in the brand (never a teammate's) and `defaultVoiceId`, the one generate_voice uses when `voiceId` is omitted. - generate_voice (writes flayr data, `write` scope): Speaks `text` (max 5,000 characters) in one of your voice clones and returns `audioUrl`. - get_brand_voice (read-only): The brand's default writing voice: tone, style and keywords to write copy in. - music_tracks_list (read-only): List the brand’s uploaded music with audio URLs, source, license, attribution, duration, mood/tags and ad-use guidance. - music_tracks_create (writes flayr data, `write` scope): Add 1–50 uploaded audio tracks to a brand library atomically. - music_library_list (read-only): List the live tracks in flayr’s own sound library with title, composer, mood, uses, energy, length, a thumbnail waveform and the licence line. - music_library_sections (read-only): Get a live flayr library track’s sections (intro, lift, drop, breakdown, ending), BPM, beat offset and full waveform, to choose a clip start and length that land on a beat or section. - mercatus_store_connect (writes flayr data, `write` scope): Connects a Mercatus Liber store to a brand, the same as Connect > Store in the dashboard. - mercatus_store_status (read-only): The brand's connected Mercatus Liber store (URL, name, scopes and import state), or `store: null`. - mercatus_store_disconnect (DESTRUCTIVE): Disconnects the brand's Mercatus Liber store, the same as "Disconnect store" in the dashboard: removes the connection, its stored key and the imported products and collections (drafts are kept). - mercatus_store_import (writes flayr data, `write` scope): Imports products from the brand's connected Mercatus Liber store, the same as the dashboard's product picker. - mercatus_store_products (read-only): The brand's imported Mercatus Liber products (GID, title, handle, status, price range, image, variant count, import time), newest first, `limit` 1-100 per page with `cursor` paging, plus the import's state (`import.running`, last run). - mercatus_store_promotions (read-only): The promotions (discount codes) in the brand's connected Mercatus Liber store: id, code, kind, value, status (active or inactive), dates and redemptions. - mercatus_store_promotion_create (writes flayr data, `write` scope): Creates a promotion in the brand's Mercatus Liber store, ALWAYS inactive (a draft no shopper can use). - mercatus_store_promotion_status (writes flayr data, `write` scope): Sets a Mercatus Liber store promotion's `status` to "active" (live: shoppers can use it) or "inactive". ## REST API (v2) - Reference (OpenAPI 3): https://flayr.social/api/docs/spec · interactive docs: https://flayr.social/docs - Liveness: GET https://flayr.social/api/v2/ping answers 200 with no key ({ ok: true, authenticated: false }). To test a key, send it and check `authenticated`, not `ok`. - Errors: 401 bad key · 402 plan too low · 403 missing scope / another brand · 404 not found · 409 conflict · 422 validation · 429 rate limit. - Publishing honours the brand's safety rules: platform readiness checks, scheduled-post review (pending-review), creator-credit rules (attribution_missing), and the flayr caption/video watermark per plan. - POST /api/v2/publish: per-platform captions go in `platformText` ({ "twitter": "…" }, the same shape and limits as PATCH /api/v2/posts/{id}; saved on the draft with contentId). Unknown body fields are refused (422 unknown_fields), never silently ignored. - GET /api/v2/rotations — List brand rotations or generated weeks - POST /api/v2/rotations — Create a brand hook rotation - PATCH /api/v2/rotations — Patch rotation settings for the next generated week - GET /api/v2/music/tracks — List music tracks in a brand library - POST /api/v2/music/tracks — Register one or more uploaded music tracks - GET /api/v2/music/library — List flayr library music (live tracks) - GET /api/v2/music/library/{id}/sections — Sections, beat grid and waveform of a library track - GET /api/v2/ping — API liveness and key check - GET /api/v2/content — List content - POST /api/v2/content — Create content - POST /api/v2/brands/{id}/invites — Invite a client to view one brand - GET /api/v2/brands — List brands - POST /api/v2/brands — Create a brand - GET /api/v2/youtube/playlists — List YouTube playlists - GET /api/v2/pinterest/boards — List Pinterest boards - POST /api/v2/media/upload-url — Get a file upload URL - GET /api/v2/content/{id} — Get content by ID - PATCH /api/v2/content/{id} — Edit a draft - DELETE /api/v2/content/{id} — Delete content - POST /api/v2/publish — Publish or schedule a post - POST /api/v2/generate/text — Generate text content - POST /api/v2/generate/image — Generate image - POST /api/v2/generate/video — Generate video (async) - GET /api/v2/generate/voice — List the voices you can speak with in a brand - POST /api/v2/generate/voice — Generate a voice-over (speak a script) - GET /api/v2/brand/voices — Get default brand voice - GET /api/v2/analytics — Analytics overview - GET /api/v2/queues — List posting queues - POST /api/v2/queues — Create a posting queue - GET /api/v2/queues/{id} — Get a posting queue - PATCH /api/v2/queues/{id} — Update, pause or resume a posting queue - DELETE /api/v2/queues/{id} — Delete a posting queue - POST /api/v2/queues/{id}/items — Append drafts to a posting queue - DELETE /api/v2/queues/{id}/items/{itemId} — Remove an item from a posting queue - PATCH /api/v2/queues/{id}/items/{itemId} — Skip, retry, unschedule, retitle or move a queue item - POST /api/v2/queues/{id}/items/reorder — Reorder the waiting items of a posting queue - POST /api/v2/campaigns/builder/estimate — Estimate a campaign from a brief - POST /api/v2/campaigns/builder — Create a campaign from a brief - POST /api/v2/campaigns/builder/{id}/generate — Generate a campaign's drafts (charges Embers) - POST /api/v2/campaigns/builder/{id}/book — Book a campaign's drafts - GET /api/v2/reviews — List scheduled-post reviews - POST /api/v2/reviews/bulk — Discard or hold up to 100 scheduled-post reviews - POST /api/v2/reviews/{id} — Approve, hold or discard a scheduled post - POST /api/v2/reviews/move — Move held posts to another slot (one or many) - GET /api/v2/collab/grants — List collab shares of a brand - POST /api/v2/collab/grants — Share a character or voice with another brand - DELETE /api/v2/collab/grants/{id} — Stop a collab share - GET /api/v2/collab/approvals — List collab posts waiting for approval - GET /api/v2/approval-groups — List content waiting for approval, one group per piece - POST /api/v2/approval-groups/{groupId}/decide — Approve, redo or drop variants of one piece - GET /api/v2/approvals — List content waiting for your approval (or rejected) - POST /api/v2/approvals/bulk — Reject or archive many pending approvals - POST /api/v2/approvals/{id} — Approve or reject content held for approval - POST /api/v2/approvals/{id}/resubmit — Resubmit rejected content for approval - POST /api/v2/approvals/{id}/regenerate — Re-generate rejected content from the reviewer's reason - POST /api/v2/approvals/move — Move held content to another time (one or many) - GET /api/v2/failed — List the Failed tab (failed post platforms) - POST /api/v2/failed/dismiss — Dismiss Failed-tab rows by id - GET /api/v2/opus/projects — List linked Opus Clip projects - POST /api/v2/opus/projects — Link (and import) Opus Clip projects - POST /api/v2/opus/submit — Send a video to Opus Clip - POST /api/v2/auto-clips/submit — Cut a long video into short clips (Auto clips) - GET /api/v2/auto-clips/{jobId} — Get an Auto clips job - POST /api/v2/content/{id}/transcribe — Transcribe a Library audio or video item - GET /api/v2/content/{id}/transcribe — List an item's Transcribe runs - GET /api/v2/pronunciations — List pronunciations - POST /api/v2/pronunciations — Add a pronunciation - POST /api/v2/pronunciations/upsert — Set a pronunciation (create or update) - PATCH /api/v2/pronunciations/{id} — Edit a pronunciation - DELETE /api/v2/pronunciations/{id} — Delete a pronunciation (or dismiss a suggestion) - GET /api/v2/pronunciations/{id}/verify — Quote a pronunciation Verify - POST /api/v2/pronunciations/{id}/verify — Verify a pronunciation - GET /api/v2/pronunciations/{id}/improve — Quote a pronunciation improve round - POST /api/v2/pronunciations/{id}/improve — Run a pronunciation improve round - POST /api/v2/voice/improve/sessions/{sessionId}/choose — Choose an improve sample - POST /api/v2/voice/improve/sessions/{sessionId}/abandon — Give up on an improve session - GET /api/v2/content/{id}/qa — Read cached media QA and gate - POST /api/v2/content/{id}/qa/rerun — Re-run media QA for free - GET /api/v2/analytics/experiments — Compare posts by a label key (A/B by label) - GET /api/v2/experiments — List experiments - POST /api/v2/experiments — Create an experiment - GET /api/v2/experiments/{id} — Get an experiment - PATCH /api/v2/experiments/{id} — Update an experiment - DELETE /api/v2/experiments/{id} — Delete an experiment (content keeps its label) - GET /api/v2/experiments/{id}/results — Experiment results - GET /api/v2/experiments/{id}/readout — Experiment readout (n per arm, 90% interval, verdict) - GET /api/v2/experiments/{id}/rounds — Version test rounds - POST /api/v2/experiments/{id}/rounds — Start the next round - POST /api/v2/experiments/{id}/close-round — Close the open round - POST /api/v2/experiments/{id}/repeat-winner — Propose repeating the winner - GET /api/v2/labels/taxonomy — Get the tag preset - PUT /api/v2/labels/taxonomy — Replace the tag preset - POST /api/v2/content/suggest-tags — Suggest hashtags and @mentions per platform - POST /api/v2/content/labels — Add or remove labels on many items - POST /api/v2/content/{id}/archive — Soft-archive a draft - POST /api/v2/content/auto-tag — Re-run auto-tag (preview, then apply) - GET /api/v2/text-templates — List formats (text templates) - POST /api/v2/text-templates — Create a format - GET /api/v2/text-templates/{id} — Get a format - PATCH /api/v2/text-templates/{id} — Update a format - DELETE /api/v2/text-templates/{id} — Delete a format - GET /api/v2/growth-triggers — List comment-to-get triggers - POST /api/v2/growth-triggers — Create a comment-to-get trigger (inactive) - GET /api/v2/growth-triggers/{id} — Get a comment-to-get trigger - PATCH /api/v2/growth-triggers/{id} — Update a comment-to-get trigger - DELETE /api/v2/growth-triggers/{id} — Delete a comment-to-get trigger - GET /api/v2/growth-triggers/{id}/stats — Comment-to-get trigger stats - GET /api/v2/ads/offers — List ad platform offers - PATCH /api/v2/ads/offers/{claimId} — Record an ad platform offer claim - GET /api/v2/ads/leads/{leadId}/booking-slots — List free times to book a call with a lead - POST /api/v2/ads/leads/{leadId}/book — Book a call with a lead - GET /api/v2/brands/{id}/business-details — Get a brand's business details - PATCH /api/v2/brands/{id}/business-details — Update a brand's business details - GET /api/v2/brands/{id}/mailbox — Get a brand's connected mailbox - POST /api/v2/brands/{id}/mailbox/connect-link — Get a link to connect a brand's mailbox - POST /api/v2/brands/{id}/mailbox/test — Send a test email from a brand's mailbox - GET /api/v2/brands/{id}/mailbox/threads — List a contact's email thread with a brand - GET /api/v2/brands/{id}/sending-identity — Get a brand's sending identity - PUT /api/v2/brands/{id}/sending-identity — Set a brand's sending identity - POST /api/v2/brands/{id}/sending-identity/domain — Add a brand's sending domain - DELETE /api/v2/brands/{id}/sending-identity/domain — Remove a brand's sending domain - POST /api/v2/brands/{id}/sending-identity/domain/verify — Check a brand's sending domain - POST /api/v2/brands/{id}/sending-identity/test — Send a test email with a brand's sending identity - GET /api/v2/ads/boost-candidates — Posts worth boosting - GET /api/v2/ads/auto-judge — Auto-judge settings and proposed campaigns - GET /api/v2/ads/command-center/config — Ads command center config (flayr admin) - GET /api/v2/ads/history-backfills — Meta history import status (flayr admin) - GET /api/v2/ads/launch-review — Paused campaigns ready for review - POST /api/v2/ads/boosts — Boost a published X post (paused, proposed) - GET /api/v2/ads/audiences — List custom and lookalike audiences - POST /api/v2/ads/audiences — Create a custom or lookalike audience - POST /api/v2/ads/audiences/{audienceId}/users — Upload a customer list - GET /api/v2/ads/site-tags — Read the site ad tags - POST /api/v2/ads/site-tags — Set one network's site ad tag - GET /api/v2/ads/site-tags/tiktok/pixel — List the TikTok pixels - POST /api/v2/ads/site-tags/tiktok/pixel — Find or create the TikTok pixel and save it as the site tag - GET /api/v2/ads/page — Read the brand's ads Page - PUT /api/v2/ads/page — Set the brand's ads Page - GET /api/v2/ads/layout — The Ads page layout - GET /api/v2/ads/lead-replies — Lead response rule (messaging-ad leads) - POST /api/v2/ads/lead-replies — Set the lead response rule - GET /api/v2/ads/lead-forms/consent — Get lead consent and follow-up settings - POST /api/v2/ads/lead-forms/consent — Save lead consent and follow-up settings - POST /api/v2/ads/lead-forms/consent-copy — Copy an Instant Form with the consent checkbox - POST /api/v2/ads/lead-forms/swap-ad — Point a live lead ad at another Instant Form - GET /api/v2/brand/intelligence — Get a brand's Brand Intelligence - PATCH /api/v2/brand/intelligence — Update a brand's Brand Intelligence, colors and fonts - GET /api/v2/accounts — List connected social accounts - DELETE /api/v2/accounts/{id} — Remove one dead connection - POST /api/v2/accounts/{id}/refresh — Refresh a connected account's profile - POST /api/v2/accounts/{id}/reconnect — Start a reconnect (returns the OAuth link) - PUT /api/v2/accounts/defaults — Set the default destination for a platform - GET /api/v2/accounts/{id}/entry-points — Read a Page's DM entry points - PUT /api/v2/accounts/{id}/entry-points — Set a Page's DM entry points - DELETE /api/v2/accounts/{id}/entry-points — Remove a Page's DM entry points - GET /api/v2/attribution-rules — List attribution rules - POST /api/v2/attribution-rules — Create an attribution rule - GET /api/v2/attribution-rules/settings — Get the brand's attribution enforcement mode - PATCH /api/v2/attribution-rules/settings — Set the brand's attribution enforcement mode - GET /api/v2/attribution-rules/{id} — Get an attribution rule - PATCH /api/v2/attribution-rules/{id} — Edit an attribution rule - DELETE /api/v2/attribution-rules/{id} — Delete an attribution rule - GET /api/v2/analytics/signup-sources — Sign-ups by source (owner brand only) - GET /api/v2/analytics/traffic — Post → site traffic (UTM visits per post and label) - POST /api/v2/insights/query — Run a custom insight - GET /api/v2/insights/dashboards — List saved insight dashboards - POST /api/v2/insights/dashboards — Create a saved insight dashboard - GET /api/v2/insights/dashboards/{id} — Get a saved insight dashboard - POST /api/v2/insights/dashboards/{id}/run — Run every tile on a saved dashboard - GET /api/v2/analytics/health — Metrics sync health - GET /api/v2/analytics/instances — Compare post instances and reruns - GET /api/v2/insights/whats-working — What's working / what isn't - POST /api/v2/content/{id}/booth-take — Attach a recorded voice-over take to a video (async) - POST /api/v2/content/{id}/combine — Combine clips into a finished video (async) - GET /api/v2/generate/status/{jobId} — Job status - POST /api/v2/media/large-upload — Begin a resumable large-media upload - POST /api/v2/video-studio/take-lists — Create a multi-take project - GET /api/v2/video-studio/take-lists/{id} — A multi-take project with its joined timeline - POST /api/v2/video-studio/take-lists/{id} — Change takes or cuts - POST /api/v2/media/takes — Save an upload as a Library draft - GET /api/v2/media/large-upload/{id} — Upload status, for resuming - POST /api/v2/media/large-upload/{id} — Record a part, renew the token, or complete - DELETE /api/v2/media/large-upload/{id} — Cancel an upload - POST /api/v2/video-studio/projects — Start a project from a saved take - GET /api/v2/video-studio/projects/{id}/progress — A project's progress - GET /api/v2/video-studio/projects/{id}/quote — What a priced step would cost - POST /api/v2/video-studio/projects/{id}/quote — Accept a quote - POST /api/v2/video-studio/projects/{id}/transcribe — Transcribe the project on an accepted quote - GET /api/v2/video-studio/projects/{id}/sections — A project's sections - POST /api/v2/video-studio/projects/{id}/sections — Section the project from its transcript - POST /api/v2/video-studio/projects/{id}/analyze — Run the signal check on an accepted quote - GET /api/v2/video-studio/projects/{id}/flags — A project's flags - POST /api/v2/video-studio/projects/{id}/flags — Decide a flag - GET /api/v2/video-studio/projects/{id}/board — The section board - POST /api/v2/video-studio/projects/{id}/board — Change a decision - GET /api/v2/video-studio/projects/{id}/auto — Auto-edit suggestions - POST /api/v2/video-studio/projects/{id}/auto — Run the auto pass, or decide a suggestion - POST /api/v2/video-studio/projects/{id}/plan — Compile the decisions into a plan - GET /api/v2/video-studio/projects/{id}/render — A project's versions - POST /api/v2/video-studio/projects/{id}/render — Make a version - GET /api/v2/video-studio/projects/{id}/cuts — A project's saved versions and its final cut - POST /api/v2/video-studio/projects/{id}/cuts — Save a draft, save the final cut, or reopen a version - POST /api/v2/video-studio/take-lists/{id}/render — Get a multi-take project ready to render - POST /api/v2/video-studio/projects/{id}/review — Run the AI production review on an accepted quote - POST /api/v2/video-studio/templates/poem/render — Render a verbatim poem into drafts - POST /api/v2/video-studio/templates/step-series/render — Render a numbered step series (Record Room) into drafts - POST /api/v2/video-studio/templates/motion-ad-from-card/render — Render a motion ad from a Library card - GET /api/v2/video-studio/segment-ads — List a brand's ad segments - POST /api/v2/video-studio/segment-ads — Generate an ad for a brand segment - POST /api/v2/video-studio/segment-ads/voice — Voice a rendered segment ad - POST /api/v2/video-studio/templates/teardown/plan — Plan a teardown film from a 3D model - POST /api/v2/video-studio/ad-cut/lint — Lint an ad cut against the ad-cut rules - GET /api/v2/posts/{id} — Get a scheduled post's first comments - PATCH /api/v2/posts/{id} — Edit or reschedule a scheduled post (caption, first comments, time) - DELETE /api/v2/posts/{id} — Cancel a scheduled post - GET /api/v2/posts/{id}/analytics — One post's full analytics, per network, with video drop-off - GET /api/v2/analytics/videos — Video and reel explorer: length against watch-through, sections, hook board - GET /api/v2/analytics/videos/compare — Overlay the retention curves of two or more videos - GET /api/v2/posts/{id}/siblings — A post's siblings: the same video elsewhere and other variants - GET /api/v2/posts/{id}/memo — Read a post's "when it posts" memo - PUT /api/v2/posts/{id}/memo — Replace a post's "when it posts" memo - GET /api/v2/characters — List activated characters - GET /api/v2/characters/{id}/bible — Read a character's draft bible - PATCH /api/v2/characters/{id}/bible — Edit a character's draft bible - GET /api/v2/characters/{id}/rounds — List a character's Look rounds - POST /api/v2/characters/{id}/rounds/feedback — Save feedback on a Look round - POST /api/v2/characters/{id}/rounds/next-round — Suggest look changes for the next round - POST /api/v2/characters/{id}/rounds/apply — Accept look changes from a round - POST /api/v2/characters/{id}/rounds/concepts — Make the next Look round's 4 concepts - POST /api/v2/characters/{id}/rounds/use-as-reference — Use a generated image as reference art - POST /api/v2/characters/{id}/rounds/own-art-note — "This is my own art" on a look-alike flag - POST /api/v2/characters/{id}/scenes — Make a scene with a character - GET /api/v2/characters/{id}/motion — List a character's motion library - POST /api/v2/characters/{id}/motion/batch — Build the motion library (batch) - GET /api/v2/characters/{id}/motion/{clipId} — One clip and its takes - PATCH /api/v2/characters/{id}/motion/{clipId} — Tag, approve or retire a clip - POST /api/v2/characters/{id}/motion/{clipId}/rounds — Iterate a clip: feedback, next take, regenerate - POST /api/v2/characters/{id}/motion/puppet — Make a silent 2D puppet clip - GET /api/v2/characters/{id}/motion/puppet — A silent puppet render's status - GET /api/v2/characters/{id}/storyboards — List a character's storyboards - POST /api/v2/characters/{id}/storyboards — Create a storyboard (brief → draft) - GET /api/v2/characters/{id}/storyboards/{sid} — One storyboard and its revisions - PATCH /api/v2/characters/{id}/storyboards/{sid} — Edit a storyboard: fields, shots, keyframes, pins - POST /api/v2/characters/{id}/storyboards/{sid}/plan — Plan reuse for a storyboard - POST /api/v2/characters/{id}/storyboards/{sid}/assemble — Assemble a storyboard into a video - GET /api/v2/characters/{id}/storyboards/{sid}/status — A storyboard's assembly status - GET /api/v2/characters/{id}/offers — What a character's build credit includes - GET /api/v2/automations/reshare-rules — List share rules - POST /api/v2/automations/reshare-rules — Create a share rule - GET /api/v2/automations/reshare-rules/{id} — Get a share rule - PATCH /api/v2/automations/reshare-rules/{id} — Update a share rule - DELETE /api/v2/automations/reshare-rules/{id} — Delete a share rule - GET /api/v2/automations/actions — List publish actions (comments after publish, reshares) - GET /api/v2/automations/actions/{id} — Get a publish action - POST /api/v2/automations/actions/{id} — Approve, reject, retry or cancel a publish action - GET /api/v2/posts/{id}/comments — List a post's comments after publish and reshares - POST /api/v2/posts/{id}/comments — Add comments after publish to a post - GET /api/v2/frames — List frames - POST /api/v2/frames — Add a frame to the library - GET /api/v2/frames/{id} — Get a frame - PATCH /api/v2/frames/{id} — Update a frame - DELETE /api/v2/frames/{id} — Delete a frame - POST /api/v2/frames/apply — Frame an image - GET /api/v2/frames/settings — Get auto-frame settings - POST /api/v2/frames/settings — Set auto-frame for a platform - POST /api/v2/frames/import — Bulk-import frames into a brand (flayr admin) - DELETE /api/v2/frames/import/{batchId} — Undo a frames import (flayr admin) - POST /api/v2/hook-studio/offers — Capture offers - GET /api/v2/hook-studio/offers — List offers - PATCH /api/v2/hook-studio/offers — Update an offer - POST /api/v2/hook-studio/hooks/generate — Generate hooks - GET /api/v2/hook-studio/hooks — List hooks - PATCH /api/v2/hook-studio/hooks — Update a hook - POST /api/v2/hook-studio/bodies/map — Map bodies - POST /api/v2/hook-studio/ctas/generate — Generate CTAs - GET /api/v2/hook-studio/ctas — List CTAs - POST /api/v2/hook-studio/ctas — Add a CTA - PATCH /api/v2/hook-studio/ctas — Update a CTA - GET /api/v2/hook-studio/cta-settings — Goals and CTA check settings - PATCH /api/v2/hook-studio/cta-settings — Update CTA check settings - POST /api/v2/hook-studio/claims/check — Check claims - POST /api/v2/cta-check — Check a CTA before an ad - GET /api/v2/ads/destinations — List landing destinations - GET /api/v2/ads/accounts — List ad accounts - POST /api/v2/ads/accounts — Select the ad account for one network - GET /api/v2/ads/campaigns — List ad campaigns - POST /api/v2/ads/campaigns — Create a paused ad campaign: Meta (Instant Form lead, click-to-message, website), TikTok, X, Google, LinkedIn, Reddit or Pinterest - GET /api/v2/ads/campaigns/{id} — Get an ad campaign - DELETE /api/v2/ads/campaigns/{id} — Delete an ad campaign - POST /api/v2/ads/campaigns/{id}/pause — Pause an ad campaign - POST /api/v2/ads/campaigns/{id}/stop — Stop an ad campaign - GET /api/v2/ads/snapshots — Read saved ads snapshots - POST /api/v2/ads/snapshots — Collect an immutable ads data snapshot - GET /api/v2/ads/insights — Ad insights - GET /api/v2/ads/readiness — Ads readiness - GET /api/v2/campaigns/{id}/review — Get a campaign's review sections - POST /api/v2/campaigns/{id}/review — Group a campaign into review sections - POST /api/v2/campaigns/{id}/review/sections/{sectionId} — Approve, fix or drop a review section - GET /api/v2/campaigns/analytics — Campaigns first: running and recent campaigns with their numbers - GET /api/v2/campaigns/{id}/analytics — One campaign's full analytics - GET /api/v2/campaigns/compare — Compare campaigns side by side - GET /api/v2/ads/caps — Read the spend caps, agent ceilings and account limit headroom - POST /api/v2/ads/caps — Set the activation spend caps - POST /api/v2/ads/accounts/spend-limit — Set the ad account spending limit - POST /api/v2/ads/ad-sets/{id}/placements — Edit ad set placements - POST /api/v2/ads/ad-sets/{id}/dataset — Attach a dataset (pixel) to an ad set - POST /api/v2/ads/campaigns/{id}/approve — Approve (and activate) a proposed campaign - POST /api/v2/ads/campaigns/{id}/budget — Scale a campaign budget - GET /api/v2/ads/targeting/search — Search ad targeting (interests) - GET /api/v2/ads/lead-forms — List Instant Forms (lead forms) - POST /api/v2/ads/lead-forms — Create an Instant Form (lead form) - POST /api/v2/ads/conversions/test-events — Send one test conversion event (Meta test_event_code) - GET /api/v2/ads/agent/activity — Agent activity - GET /api/v2/ads/deep-dives — List saved deep dives - POST /api/v2/ads/deep-dives — Run a deep dive on a saved snapshot - GET /api/v2/ads/deep-dives/quote — Quote a deep dive - GET /api/v2/ads/deep-dives/compare — Compare two deep dives - GET /api/v2/ads/campaigns/{id}/checkpoints — Read a campaign's scheduled check-ins - POST /api/v2/ads/campaigns/{id}/checkpoints — Switch a campaign's scheduled check-ins on or off - GET /api/v2/ads/deep-dives/{id} — Read or export one deep dive - GET /api/v2/ads/learned-insights — Read the ads insights library (FFE-1076) - GET /api/v2/ads/imports — Read campaign import state - POST /api/v2/ads/imports — Import one page of prior campaigns - GET /api/v2/ads/imports/files — List stats file imports - POST /api/v2/ads/imports/files — Import prior campaign stats from an export - POST /api/v2/ads/imports/files/preview — Preview a stats file import - GET /api/v2/ads/imports/files/{id} — Read one stats file import - POST /api/v2/ads/imports/files/{id}/undo — Undo one stats file import - GET /api/v2/campaign-shares — List sample campaign review links - POST /api/v2/campaign-shares — Make a sample campaign review link - GET /api/v2/campaign-shares/{id} — Read the verdicts on a review link - DELETE /api/v2/campaign-shares/{id} — Revoke a review link - GET /api/v2/pool/state — Trial posting-spot pool: public state plus admin counts - POST /api/v2/pool/expand — Ask to open the next ladder step of posting spots (the server re-checks and may refuse) - POST /api/v2/pool/notify — Send the notification for one pool.* event, then ack it - GET /api/v2/pool/waitlist-digest — What the waitlist nudger would do now (counts only) - POST /api/v2/pool/waitlist-digest — Send the due waitlist nudges (at most one per person per nudgeEveryDays, 100 per call) - POST /api/v2/stores/mercatus/connect — Connect a Mercatus Liber store - GET /api/v2/stores/mercatus/connect — Get the brand's Mercatus store - DELETE /api/v2/stores/mercatus/connect — Disconnect the brand's Mercatus store - POST /api/v2/stores/mercatus/import — Import or refresh the Mercatus store's products - GET /api/v2/stores/mercatus/import — List the Mercatus store's imported products - GET /api/v2/stores/mercatus/promotions — List the Mercatus store's promotions - POST /api/v2/stores/mercatus/promotions — Create a draft promotion in the Mercatus store - PATCH /api/v2/stores/mercatus/promotions/{id} — Switch a Mercatus store promotion on or off ## Complete OpenAPI specification ```json {"openapi":"3.0.3","info":{"title":"Flayr API","version":"1.0.0","description":"AI-powered social content creation and publishing platform. All endpoints require a Bearer token (Clerk session token or API key) unless otherwise noted.\n\n**AI agents (MCP):** the same v2 API is served as a remote MCP server at `/api/mcp` (Streamable HTTP, API key as Bearer token, Pro+ plan). Claude Code: `claude mcp add --transport http flayr https://flayr.social/api/mcp --header \"Authorization: Bearer flayr_sk_…\"`. Tool list and agent guide: [/llms.txt](/llms.txt).","contact":{"name":"Flayr Support","url":"https://flayr.social"}},"servers":[{"url":"https://flayr.social","description":"Production"}],"components":{"securitySchemes":{"opsKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"flayr_ops_…","description":"Owner-issued ops key. Scopes: admin:flags, admin:config, admin:deliver-samples, support:requests, ops:landing, ops:booking-gate, ops:money (billing flags; founder approval), ops:help (help-center tutorial videos), support:invites (comp-plan invites), support:accounts (account lookup and time-boxed comps), support:samples-setup (samples workspaces). Issue at /super-admin/ops-keys using a super-admin session; send Authorization: Bearer flayr_ops_…."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk session token (obtained via Clerk JS SDK) or a Flayr API key. Pass as `Authorization: Bearer `."}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"Authentication required"},"code":{"type":"string","example":"UNAUTHORIZED"}}},"Pagination":{"type":"object","properties":{"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null when exhausted.","example":"cnt_01HZ9KQF3B"},"total":{"type":"integer","example":42}}},"UsageInfo":{"type":"object","properties":{"promptTokens":{"type":"integer","example":120},"completionTokens":{"type":"integer","example":340},"totalTokens":{"type":"integer","example":460}}},"Platform":{"type":"string","enum":["instagram","twitter","x","tiktok","facebook","linkedin","youtube","pinterest","threads","bluesky","reddit","telegram","whatsapp","google_business"],"example":"instagram","description":"Target platform for the post. Posting behavior and limits differ significantly per platform — see https://docs.zernio.com/platforms/{platform} for the authoritative per-platform reference (what Flayr posts through under the hood). Notable constraints: `youtube` — full video-via-URL upload, up to 256GB/video, max duration 15min on an unverified channel / 12hr verified; clips ≤3min in a vertical aspect ratio are auto-classified as Shorts; Community posts, Premieres, end screens, cards, and captions are NOT supported via the API. Other platforms: check the Zernio docs link above for that platform before assuming parity with what the dashboard UI shows."},"ContentStatus":{"type":"string","enum":["draft","scheduled","posted","archived"],"example":"draft"},"ContentItem":{"type":"object","required":["id","userId","text","platforms","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"cnt_01HZ9KQF3B"},"userId":{"type":"string","example":"user_2abc123"},"text":{"type":"string","example":"Exciting news from our team!"},"imageUrl":{"type":"string","format":"uri","nullable":true},"audioUrl":{"type":"string","format":"uri","nullable":true},"videoUrl":{"type":"string","format":"uri","nullable":true},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/Platform"},"example":["instagram","tiktok"]},"status":{"$ref":"#/components/schemas/ContentStatus"},"aiModel":{"type":"string","nullable":true,"example":"gemini-flash-38"},"prompt":{"type":"string","nullable":true,"example":"Write a post about our new product"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WorkflowStatus":{"type":"string","enum":["draft","active","paused","archived"],"example":"active"},"WorkflowNode":{"type":"object","required":["id","type","label","x","y","config","ports"],"properties":{"id":{"type":"string","example":"node_1"},"type":{"type":"string","example":"ai:text"},"label":{"type":"string","example":"Generate Text"},"x":{"type":"number","example":100},"y":{"type":"number","example":200},"config":{"type":"object","additionalProperties":true},"ports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"direction":{"type":"string","enum":["input","output"]}}}}}},"WorkflowEdge":{"type":"object","required":["id","sourceNodeId","sourcePortId","targetNodeId","targetPortId"],"properties":{"id":{"type":"string","example":"edge_1"},"sourceNodeId":{"type":"string","example":"node_1"},"sourcePortId":{"type":"string","example":"out-0"},"targetNodeId":{"type":"string","example":"node_2"},"targetPortId":{"type":"string","example":"in-0"}}},"WorkflowItem":{"type":"object","required":["id","userId","name","status","nodes","edges","config","runCount","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wf_01HZ"},"userId":{"type":"string","example":"user_2abc123"},"name":{"type":"string","example":"Daily Instagram Post"},"description":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/WorkflowStatus"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowEdge"}},"config":{"type":"object","additionalProperties":true},"runCount":{"type":"integer","example":5},"lastRunAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SocialAccount":{"type":"object","properties":{"_id":{"type":"string","example":"acc_01HZ9KQF"},"platform":{"$ref":"#/components/schemas/Platform"},"username":{"type":"string","example":"@flayr_social"},"displayName":{"type":"string","example":"Flayr Social"},"avatarUrl":{"type":"string","format":"uri","nullable":true},"connected":{"type":"boolean","example":true}}},"ApiKey":{"type":"object","required":["id","name","createdAt"],"properties":{"id":{"type":"string","example":"key_01HZ"},"name":{"type":"string","example":"Production key"},"keyPrefix":{"type":"string","example":"flayr_sk_abc1","description":"First few characters of the key for identification. Full key only shown on creation."},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true}}},"ApiKeyCreated":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","required":["key"],"properties":{"key":{"type":"string","example":"flayr_sk_abc123456789","description":"Full API key. Only returned once on creation — store securely."}}}]},"ScheduleStatus":{"type":"string","enum":["scheduled","publishing","published","failed","cancelled"],"example":"scheduled"},"ScheduleItem":{"type":"object","required":["id","contentId","userId","platform","scheduledAt","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sch_01HZ"},"contentId":{"type":"string","example":"cnt_01HZ"},"userId":{"type":"string","example":"user_2abc123"},"platform":{"$ref":"#/components/schemas/Platform"},"scheduledAt":{"type":"string","format":"date-time"},"status":{"$ref":"#/components/schemas/ScheduleStatus"},"postedAt":{"type":"string","format":"date-time","nullable":true},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"VoiceCloneStatus":{"type":"string","enum":["processing","ready","failed"],"example":"ready"},"VoiceClone":{"type":"object","required":["id","userId","name","voiceId","status","durationSeconds","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"vc_01HZ"},"userId":{"type":"string","example":"user_2abc123"},"name":{"type":"string","example":"My Voice"},"voiceId":{"type":"string","example":"voice_abc123"},"sampleUrl":{"type":"string","format":"uri","nullable":true},"status":{"$ref":"#/components/schemas/VoiceCloneStatus"},"errorMessage":{"type":"string","nullable":true},"durationSeconds":{"type":"number","example":45.2},"voiceSettings":{"$ref":"#/components/schemas/VoiceSettings"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"VoiceSettings":{"type":"object","description":"A voice clone's Chatterbox settings. At 0.5 / 0.5 (the default) the clone speaks on the fast engine; other values speak on the expressive engine.","required":["exaggeration","cfgWeight"],"properties":{"exaggeration":{"type":"number","minimum":0.25,"maximum":2,"example":0.7,"description":"Expressiveness. Default 0.5."},"cfgWeight":{"type":"number","minimum":0,"maximum":1,"example":0.3,"description":"Pacing (lower is slower). Default 0.5."}}},"Contact":{"type":"object","required":["id","userId","name","platform","createdAt"],"properties":{"id":{"type":"string","example":"con_01HZ"},"userId":{"type":"string","example":"user_2abc123"},"name":{"type":"string","example":"Jane Smith"},"platform":{"type":"string","example":"instagram"},"username":{"type":"string","nullable":true,"example":"@janesmith"},"email":{"type":"string","format":"email","nullable":true},"avatarUrl":{"type":"string","format":"uri","nullable":true},"isSubscribed":{"type":"boolean","example":true},"tags":{"type":"array","items":{"type":"string"}},"customFields":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"}}},"BrandProfile":{"type":"object","required":["id","userId","name","createdAt"],"properties":{"id":{"type":"string","example":"bp_01HZ"},"userId":{"type":"string","example":"user_2abc123"},"name":{"type":"string","example":"Main Brand"},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/Platform"}},"voice":{"type":"object","properties":{"tone":{"type":"string","nullable":true},"style":{"type":"string","nullable":true},"keywords":{"type":"array","items":{"type":"string"}},"avoidWords":{"type":"array","items":{"type":"string"}}}},"primaryColor":{"type":"string","nullable":true,"example":"#FF5733"},"logoUrl":{"type":"string","format":"uri","nullable":true},"isDefault":{"type":"boolean","example":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"VideoJobStatus":{"type":"string","enum":["pending","processing","completed","failed"],"example":"pending"}},"responses":{"Unauthorized":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Authentication required"}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum requests per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit window resets.","schema":{"type":"integer"}}}},"Forbidden":{"description":"Authenticated but lacking the required plan or feature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Upgrade to Standard or higher for direct posting"}}}},"RateLimited":{"description":"Monthly usage limit reached. Upgrade to continue.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"object","properties":{"limit":{"type":"integer","example":50},"used":{"type":"integer","example":50},"tier":{"type":"string","example":"free"}}}]}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Internal Server Error"}}}}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Health","description":"System status and readiness checks."},{"name":"Generation","description":"AI-powered content generation."},{"name":"Content","description":"Content library — CRUD for generated posts."},{"name":"Social","description":"Social account management and publishing."},{"name":"Workflows","description":"Automation workflow definitions and execution."},{"name":"Image Processing","description":"Server-side image transforms via Sharp."},{"name":"API Keys","description":"Programmatic access key management."},{"name":"Schedule","description":"Schedule content for future publishing."},{"name":"Broadcasts","description":"Bulk message broadcasts to contact segments."},{"name":"Sequences","description":"Multi-step automated message sequences."},{"name":"Contacts","description":"CRM contact and tag management."},{"name":"Voice","description":"Voice clone creation and text-to-speech generation."},{"name":"Brand","description":"Brand profile management and AI-driven brand analysis."},{"name":"Analytics","description":"Engagement and performance analytics."},{"name":"Video","description":"Video composition and export jobs."},{"name":"Social Queue","description":"Publishing queue slot management via Zernio."},{"name":"Social Inbox","description":"Unified social DM inbox powered by Zernio."},{"name":"Social Comments","description":"Comment management across social platforms."},{"name":"Media","description":"Authenticated media file streaming."},{"name":"Inference","description":"On-demand speech synthesis."},{"name":"Ops: sample deliveries","description":"Owner-issued ops keys for staff sample delivery; customer approval remains required."},{"name":"Ops: staff switches","description":"Owner-issued ops keys for the landing split and booking-gate config; every change is audited."},{"name":"Ops: support","description":"Owner-issued ops keys for 24/7 support: invites with a comp plan, account lookups and comps, samples workspaces; every action is audited."},{"name":"Notifications","description":"In-app notification management."}],"paths":{"/api/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Returns the overall status and one status for each customer-facing component (App, Posting, AI generation, Scheduling, Payments, Email). Always answers HTTP 200; read `status`. `watchdog` is the heartbeat of the internal check that looks for automations that stopped posting: when its scheduled run last finished, and `stale` when that is older than `staleAfterHours`. It does not change `status`. This endpoint is **public** — no authentication required.","operationId":"getHealth","security":[],"responses":{"200":{"description":"Service status — may be `ok` or `degraded`.","content":{"application/json":{"schema":{"type":"object","required":["status","timestamp","environment","components"],"properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"`ok` only when every component is operational.","example":"ok"},"timestamp":{"type":"string","format":"date-time"},"environment":{"type":"string","example":"production"},"components":{"type":"array","items":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string","example":"posting"},"name":{"type":"string","example":"Posting"},"status":{"type":"string","enum":["operational","degraded","outage"]}}}},"watchdog":{"type":"object","required":["status","lastRunAt","staleAfterHours"],"description":"Heartbeat of the automation watchdog. No customer data.","properties":{"status":{"type":"string","enum":["ok","stale","never","disabled","unknown"],"description":"`stale`: the last scheduled run is older than `staleAfterHours`. `never`: no scheduled run on this deployment yet. `disabled`: switched off. `unknown`: could not be read.","example":"ok"},"lastRunAt":{"type":"string","format":"date-time","nullable":true},"staleAfterHours":{"type":"number","nullable":true,"example":26}}}}}}}}}}},"/api/generate/text":{"post":{"tags":["Generation"],"summary":"Generate text content","description":"Uses the AI model appropriate for the caller's subscription tier to produce short, long, and hashtag variations for a given topic.","operationId":"generateText","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topic"],"properties":{"topic":{"type":"string","example":"New product launch for our event management app","description":"The subject or theme for the generated content."},"style":{"type":"string","default":"professional","example":"casual","description":"Tone of voice. E.g. \"professional\", \"casual\", \"inspirational\", \"humorous\"."},"templateId":{"type":"string","nullable":true,"description":"Optional template ID to guide content structure."},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/Platform"},"default":[],"description":"Target platforms — used to tailor content length and hashtags.","example":["instagram","linkedin"]}}}}}},"responses":{"200":{"description":"Generated content variations.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"Convex generation job ID for tracking.","example":"j7abc123"},"variations":{"type":"object","properties":{"short":{"type":"string","description":"Concise caption (1–2 sentences).","example":"Exciting news! Our new app is live."},"long":{"type":"string","description":"Long-form post or thread content."},"hashtags":{"type":"string","description":"10–15 relevant hashtags.","example":"#eventtech #launch #SaaS"}}},"usage":{"$ref":"#/components/schemas/UsageInfo"}}}}}},"400":{"description":"Missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Topic is required"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/ai/chat":{"post":{"tags":["Generation"],"summary":"Streaming chat","description":"Streams an AI chat response using Vercel AI SDK data-stream protocol. The response body is a text stream — each line is prefixed with `0:` for content chunks. Use the AI SDK `useChat` hook or parse manually.","operationId":"aiChat","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","minItems":1,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant","system"],"example":"user"},"content":{"type":"string","example":"Write a compelling caption for my product launch."}}}},"model":{"type":"string","default":"gemini-flash","description":"Model alias. Actual model resolved by tier.","example":"gemini-flash"},"template":{"type":"string","nullable":true,"description":"Optional template name to prime the system prompt."},"platform":{"$ref":"#/components/schemas/Platform"}}}}}},"responses":{"200":{"description":"Vercel AI SDK data stream (text/plain).","content":{"text/plain":{"schema":{"type":"string","description":"Line-delimited stream. Content tokens are prefixed with `0:`, metadata with `d:`. Example: `0:\"Hello\"\\n0:\" world\"\\nd:{...}`"}}}},"400":{"description":"Invalid or empty messages array.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/ai/image":{"post":{"tags":["Generation"],"summary":"Generate an image","description":"Generates an image using Gemini image generation. The result is persisted to the content library as a draft. Usage is tracked against monthly limits.","operationId":"aiImage","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"A vibrant concert crowd at sunset, cinematic lighting"},"aspectRatio":{"type":"string","default":"1:1","enum":["1:1","16:9","9:16","4:5"],"example":"9:16"},"style":{"type":"string","default":"vivid","enum":["vivid","natural"]}}}}}},"responses":{"200":{"description":"Generated image URL.","content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string","format":"uri","example":"https://storage.convex.cloud/..."},"storageId":{"type":"string","nullable":true,"description":"Convex storage ID if persisted."},"prompt":{"type":"string"}}}}}},"400":{"description":"Missing prompt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Image generation provider not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/ai/video":{"post":{"tags":["Generation"],"summary":"Generate a video","description":"Starts asynchronous video generation via Google Veo 2 (Vertex AI). Returns immediately with a `jobId` and `status: \"processing\"`. Poll the generation job via Convex or check the content library when done. Requires a Standard plan or higher.","operationId":"aiVideo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"A time-lapse of a sold-out event venue filling with guests"},"duration":{"type":"integer","default":6,"minimum":1,"maximum":60,"description":"Video duration in seconds.","example":6},"aspectRatio":{"type":"string","default":"9:16","enum":["9:16","16:9","1:1"],"example":"9:16"},"audio":{"description":"Native audio & dialogue for models that generate their own soundtrack through the AI Gateway (Veo 3.x, Seedance 2.x, Kling 3.0, FLUX 3 Video, MiniMax H3, Grok Imagine 1.5). `true`/`false` or an object. Dialogue is spoken in the model's own voice, not a cloned one, and is trimmed to about 2.5 words per second of clip. Omitted = the model's default. Ignored by models without native audio. Veo 3.1 Fast with audio on costs 75 Embers per second instead of 50.","oneOf":[{"type":"boolean"},{"type":"object","properties":{"enabled":{"type":"boolean","description":"Native audio on/off. Off unless set to true (opt-in; dialogue and hints are ignored without it)."},"dialogue":{"type":"string","maxLength":600,"description":"Lines to be spoken (dialogue or narration)."},"voiceHint":{"type":"string","maxLength":200,"example":"woman in her 30s, warm and confident"},"soundHint":{"type":"string","maxLength":200,"example":"soft rain, distant city traffic"}}}]}}}}}},"responses":{"200":{"description":"Video generation job started.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","example":"job_1714000000000_abc123"},"status":{"type":"string","enum":["processing"]}}}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"GCP credentials not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/ai/caption":{"post":{"tags":["Generation"],"summary":"Generate a caption","description":"Generates a platform-optimised caption and hashtag set for a given topic. Requires the `ai_captions` feature flag (Pro plan).","operationId":"aiCaption","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topic"],"properties":{"topic":{"type":"string","example":"Summer music festival highlights"},"template":{"type":"string","nullable":true,"example":"event-recap"},"tone":{"type":"string","default":"engaging","example":"enthusiastic"},"platform":{"$ref":"#/components/schemas/Platform"}}}}}},"responses":{"200":{"description":"Generated caption and hashtags.","content":{"application/json":{"schema":{"type":"object","properties":{"caption":{"type":"string","example":"What an incredible night! The crowd was electric ✨"},"hashtags":{"type":"array","items":{"type":"string"},"example":["#festival","#music","#summer2026"]},"estimatedReach":{"type":"integer","example":5000}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Feature requires a plan upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/content":{"get":{"tags":["Content"],"summary":"List content items","description":"Returns a paginated list of content items for the authenticated user.","operationId":"listContent","parameters":[{"name":"platform","in":"query","schema":{"$ref":"#/components/schemas/Platform"},"description":"Filter to a specific target platform."},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ContentStatus"},"description":"Filter by content status."},{"name":"search","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring search against the text field.","example":"product launch"},{"name":"after","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only return items created after this ISO-8601 timestamp."},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only return items created before this ISO-8601 timestamp."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor from a previous response."},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Maximum items to return per page."}],"responses":{"200":{"description":"Paginated content list.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentItem"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Content"],"summary":"Create content item","description":"Creates a new content item in the library. At minimum a `text` body and at least one `platform` are required.","operationId":"createContent","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","platforms"],"properties":{"text":{"type":"string","example":"Join us for the biggest event of the year!"},"imageUrl":{"type":"string","format":"uri","nullable":true},"images":{"type":"array","items":{"type":"string","format":"uri"},"nullable":true,"description":"Array of image URLs for multi-image posts (e.g. carousels)."},"audioUrl":{"type":"string","format":"uri","nullable":true},"videoUrl":{"type":"string","format":"uri","nullable":true},"platforms":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Platform"},"example":["instagram","facebook"]},"status":{"$ref":"#/components/schemas/ContentStatus"},"aiModel":{"type":"string","nullable":true},"prompt":{"type":"string","nullable":true},"contentType":{"type":"string","nullable":true,"enum":["text","image","video","audio","carousel"]},"slides":{"type":"array","nullable":true,"items":{"type":"object","required":["order"],"properties":{"text":{"type":"string"},"imageUrl":{"type":"string","format":"uri"},"order":{"type":"integer"}}}}}}}}},"responses":{"201":{"description":"Content item created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"j7kx9abc"},"externalId":{"type":"string","example":"cnt_01HZ9KQF3B"}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/accounts":{"get":{"tags":["Social"],"summary":"List connected accounts","description":"Returns all social accounts connected to the user's Zernio profile. Pass `health=true` to include per-account token health information.","operationId":"listSocialAccounts","parameters":[{"name":"health","in":"query","schema":{"type":"boolean","default":false},"description":"Include account health / token validity data."}],"responses":{"200":{"description":"List of connected social accounts.","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/SocialAccount"}},"health":{"type":"array","description":"Only present when `health=true` is requested.","items":{"type":"object","properties":{"accountId":{"type":"string"},"status":{"type":"string","enum":["ok","expired","revoked"]}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/post":{"post":{"tags":["Social"],"summary":"Publish to social platforms","description":"Creates and optionally publishes a post to one or more connected social accounts via Zernio. Requires the `direct_posting` feature (Standard plan or higher). Content is automatically formatted to meet each platform's constraints. (flayr#2291) Per-platform behavior varies a lot beyond text formatting — media size/duration limits, which features the API can/can't use (e.g. YouTube Community posts, Premieres, and captions are NOT supported via this endpoint), and format auto-classification rules (e.g. short vertical YouTube clips become Shorts automatically). See the `platforms` field's Platform schema description, or https://docs.zernio.com/platforms/{platform} for the full per-platform reference.","operationId":"createSocialPost","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content","platforms"],"properties":{"content":{"type":"string","example":"Tickets are now on sale! Grab yours before they're gone.","description":"The post text. Automatically truncated per platform limits."},"platforms":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Platform"},"example":["instagram","twitter"]},"publishNow":{"type":"boolean","default":true,"description":"Publish immediately. Ignored when `scheduledFor` is set."},"scheduledFor":{"type":"string","format":"date-time","nullable":true,"description":"ISO-8601 timestamp for scheduled publishing. Omit to publish now or queue.","example":"2026-05-01T09:00:00Z"},"mediaUrls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Media attachments (images or video)."},"contentId":{"type":"string","description":"The saved draft this post comes from. Its readiness (placeholders, open claims, article format, teaser gate) is checked, and its stored LinkedIn first comment is used when none is sent."},"document":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":200}},"description":"Post the draft's rendered PDF (`contentId` required) as a LinkedIn document (carousel) post, titled `title`. LinkedIn only; no other media. The PDF URL always comes from the draft."},"platformSpecificData":{"type":"object","additionalProperties":true,"description":"Per-platform overrides (e.g. alt text for Instagram, first-comment hashtags). Keyed by platform name.","example":{"instagram":{"firstComment":"#eventtech #launch"}}}}}}}},"responses":{"200":{"description":"Post created (and published or scheduled).","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Zernio post ID.","example":"zpost_01HZ"},"formattingWarnings":{"type":"array","items":{"type":"string"},"description":"Non-fatal warnings about content adjustments made for platform compliance."}}}}}},"400":{"description":"Missing required fields or platform constraint violation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/disconnect/{platform}":{"delete":{"tags":["Social"],"summary":"Disconnect a social account","operationId":"disconnectSocialAccount","parameters":[{"name":"platform","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Platform"}}],"responses":{"200":{"description":"Disconnected.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/connections":{"get":{"tags":["Social"],"summary":"Sync and list connected accounts","description":"Fetches connected accounts from Zernio, upserts them into Convex, and returns the normalized list.","operationId":"getSocialConnections","responses":{"200":{"description":"Connected accounts.","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"handle":{"type":"string"},"id":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Zernio not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/social/accounts/sync":{"post":{"tags":["Social"],"summary":"Sync Zernio accounts to Convex","description":"Fetches all accounts from Zernio and upserts them into Convex socialAccounts.","operationId":"syncSocialAccounts","responses":{"200":{"description":"Sync results.","content":{"application/json":{"schema":{"type":"object","properties":{"synced":{"type":"integer","example":3},"total":{"type":"integer","example":3}}}}}},"400":{"description":"Zernio profile not connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/post/{postId}/retry":{"post":{"tags":["Social"],"summary":"Retry a failed post","operationId":"retrySocialPost","parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retry initiated.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Missing postId or Zernio not connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/workflows":{"get":{"tags":["Workflows"],"summary":"List workflows","description":"Returns all automation workflows owned by the authenticated user.","operationId":"listWorkflows","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/WorkflowStatus"},"description":"Filter by workflow status."}],"responses":{"200":{"description":"Workflow list.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowItem"}},"total":{"type":"integer","example":3}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/workflows/{id}/run":{"post":{"tags":["Workflows"],"summary":"Execute a workflow","description":"Triggers an immediate execution of the workflow DAG. The request returns as soon as a run record is created; execution continues in the background. Subscribe to `workflow_runs` in Convex to track real-time step progress.","operationId":"runWorkflow","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Convex workflow document ID.","example":"j7kx9abc"}],"responses":{"200":{"description":"Run started.","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","example":"run_01HZ"},"workflowId":{"type":"string","example":"j7kx9abc"},"status":{"type":"string","enum":["running"]},"startedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Workflow cannot be run (empty, archived, or paused).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Workflow not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/image/transform":{"post":{"tags":["Image Processing"],"summary":"Transform an image","description":"Applies one or more sequential image operations (resize, watermark, format conversion) to a source image URL using Sharp. Returns a base64 data URL of the processed image.","operationId":"imageTransform","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imageUrl","operations"],"properties":{"imageUrl":{"type":"string","format":"uri","description":"Publicly accessible URL of the source image.","example":"https://example.com/photo.jpg"},"operations":{"type":"array","minItems":1,"description":"Ordered list of transform operations to apply.","items":{"oneOf":[{"title":"Resize","type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["resize"]},"width":{"type":"integer","default":1080,"example":1080},"height":{"type":"integer","nullable":true},"fit":{"type":"string","enum":["cover","contain","fill"],"default":"cover"}}},{"title":"Watermark","type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["watermark"]},"text":{"type":"string","default":"Made with Flayr","example":"Made with Flayr"},"position":{"type":"string","enum":["bottom-right","bottom-left","top-right","top-left","center"],"default":"bottom-right","description":"Ignored if sent. Resolved server-side from the caller's saved default position (Settings → Watermark), falling back to 'bottom-right' when none is saved."},"opacity":{"type":"number","minimum":0,"maximum":1,"default":0.5}}},{"title":"Format Conversion","type":"object","required":["type","format"],"properties":{"type":{"type":"string","enum":["format"]},"format":{"type":"string","enum":["webp","png","jpeg"]},"quality":{"type":"integer","minimum":1,"maximum":100,"default":85}}}]}}}},"examples":{"resizeAndWatermark":{"summary":"Resize to 1080px then add watermark","value":{"imageUrl":"https://example.com/photo.jpg","operations":[{"type":"resize","width":1080,"fit":"cover"},{"type":"watermark","text":"Made with Flayr","opacity":0.5}]}},"formatConvert":{"summary":"Convert to WebP","value":{"imageUrl":"https://example.com/photo.png","operations":[{"type":"format","format":"webp","quality":90}]}}}}}},"responses":{"200":{"description":"Processed image as a base64 data URL.","content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string","description":"Base64 data URL of the processed image.","example":"data:image/webp;base64,/9j/4AAQ..."},"format":{"type":"string","enum":["webp","png","jpeg"]},"size":{"type":"integer","description":"Output buffer size in bytes.","example":102400}}}}}},"400":{"description":"Missing imageUrl, invalid operations, or source fetch failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/keys":{"get":{"tags":["API Keys"],"summary":"List API keys","description":"Returns all API keys for the authenticated user. Key values are never returned — only metadata.","operationId":"listApiKeys","responses":{"200":{"description":"List of API keys.","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["API Keys"],"summary":"Create API key","description":"Generates a new API key for programmatic access. The full key is **only returned once** at creation — store it securely.","operationId":"createApiKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"CI/CD integration","description":"Human-readable label for the key."},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Optional expiry timestamp. Omit for a non-expiring key.","example":"2027-01-01T00:00:00Z"}}}}}},"responses":{"201":{"description":"API key created. Store the `key` value — it will not be shown again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"400":{"description":"Missing name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["API Keys"],"summary":"Revoke API key","description":"Permanently revokes an API key. This action is irreversible.","operationId":"deleteApiKey","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"ID of the API key to revoke.","example":"key_01HZ"}],"responses":{"200":{"description":"Key revoked successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Missing key ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/schedule":{"get":{"tags":["Schedule"],"summary":"List scheduled posts","operationId":"listSchedules","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ScheduleStatus"},"description":"Filter by status."},{"name":"platform","in":"query","schema":{"$ref":"#/components/schemas/Platform"},"description":"Filter by platform."},{"name":"after","in":"query","schema":{"type":"string","format":"date-time"},"description":"Return schedules after this timestamp."},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"},"description":"Return schedules before this timestamp."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor."},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Max results (≤100)."}],"responses":{"200":{"description":"Schedule list.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ScheduleItem"}},"nextCursor":{"type":"string","nullable":true},"total":{"type":"integer","example":5}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Schedule"],"summary":"Schedule a post (retired — use POST /api/social/post)","description":"Retired. This endpoint only ever recorded a local schedule entry that was never published, so it now always answers 410 Gone. To schedule a post, call POST /api/social/post with `scheduledFor` (ISO-8601) and `publishNow: false`.","operationId":"createSchedule","deprecated":true,"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"410":{"description":"Endpoint retired. Use POST /api/social/post with `scheduledFor`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/schedule/{id}":{"patch":{"tags":["Schedule"],"summary":"Update a scheduled post","operationId":"updateSchedule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Schedule ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scheduledAt":{"type":"string","format":"date-time"},"status":{"$ref":"#/components/schemas/ScheduleStatus"}}}}}},"responses":{"200":{"description":"Updated schedule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleItem"}}}},"400":{"description":"Cannot update a published or cancelled item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Schedule not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Schedule"],"summary":"Cancel a scheduled post","operationId":"deleteSchedule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Cancelled."},"400":{"description":"Cannot cancel an already-published item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Schedule not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/broadcasts":{"get":{"tags":["Broadcasts"],"summary":"List broadcasts","operationId":"listBroadcasts","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","sending","completed","failed"]}}],"responses":{"200":{"description":"Broadcasts list.","content":{"application/json":{"schema":{"type":"object","properties":{"broadcasts":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Broadcasts"],"summary":"Create a broadcast","operationId":"createBroadcast","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","messageContent"],"properties":{"name":{"type":"string","example":"April Newsletter"},"messageContent":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"mediaUrls":{"type":"array","items":{"type":"string","format":"uri"}}}},"segmentFilter":{"type":"object","additionalProperties":true,"nullable":true,"description":"Contact segment filter criteria."},"channelId":{"type":"string","nullable":true},"scheduledFor":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"200":{"description":"Broadcast created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"bc_01HZ"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/broadcasts/{id}/send":{"post":{"tags":["Broadcasts"],"summary":"Send a broadcast","description":"Triggers chunked delivery to all matching contacts (100 contacts/chunk with 100ms delay). Returns 409 if already sending or completed.","operationId":"sendBroadcast","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Broadcast ID."}],"responses":{"200":{"description":"Send initiated.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["sending"]},"targetCount":{"type":"integer","example":500},"chunks":{"type":"integer","example":5}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Broadcast not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Broadcast already sending or completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/sequences":{"get":{"tags":["Sequences"],"summary":"List sequences","operationId":"listSequences","responses":{"200":{"description":"Sequence list.","content":{"application/json":{"schema":{"type":"object","properties":{"sequences":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Sequences"],"summary":"Create a sequence","operationId":"createSequence","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","steps"],"properties":{"name":{"type":"string","example":"Onboarding Flow"},"description":{"type":"string","nullable":true},"steps":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":true}}}}}}},"responses":{"200":{"description":"Sequence created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"seq_01HZ"}}}}}},"400":{"description":"Missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/sequences/{id}/enroll":{"post":{"tags":["Sequences"],"summary":"Enroll a contact in a sequence","operationId":"enrollSequence","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Sequence ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contactId"],"properties":{"contactId":{"type":"string","description":"Convex contact document ID."},"channelId":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Contact enrolled.","content":{"application/json":{"schema":{"type":"object","properties":{"enrollmentId":{"type":"string","example":"enr_01HZ"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Sequence not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","operationId":"listContacts","parameters":[{"name":"platform","in":"query","schema":{"$ref":"#/components/schemas/Platform"}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search by name or username."},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Contact list.","content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Contacts"],"summary":"Create a contact","operationId":"createContact","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","platform"],"properties":{"name":{"type":"string","example":"Jane Smith"},"platform":{"type":"string","example":"instagram"},"username":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"avatarUrl":{"type":"string","format":"uri","nullable":true}}}}}},"responses":{"200":{"description":"Contact created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"con_01HZ"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/contacts/tags":{"get":{"tags":["Contacts"],"summary":"List contact tags","operationId":"listContactTags","responses":{"200":{"description":"Tag list.","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Contacts"],"summary":"Create a contact tag","operationId":"createContactTag","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"VIP"},"color":{"type":"string","nullable":true,"example":"#FF5733"}}}}}},"responses":{"200":{"description":"Tag created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Contacts"],"summary":"Delete a contact tag","operationId":"deleteContactTag","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"Tag ID."}],"responses":{"200":{"description":"Tag deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Tag not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Get a contact","operationId":"getContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact detail.","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"tags":{"type":"array","items":{"type":"object","additionalProperties":true}},"fieldDefs":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Contact not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"patch":{"tags":["Contacts"],"summary":"Update a contact","operationId":"updateContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"tags":{"type":"array","items":{"type":"string"}},"customFields":{"type":"object","additionalProperties":true},"isSubscribed":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Contact updated.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Contact not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Contacts"],"summary":"Delete a contact","operationId":"deleteContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Contact not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/voice":{"get":{"tags":["Voice"],"summary":"List voice clones","operationId":"listVoiceClones","responses":{"200":{"description":"Voice clone list.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VoiceClone"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/voice/clone":{"post":{"tags":["Voice"],"summary":"Create a voice clone","description":"Upload a voice sample to create a cloneable voice. **Requires Pro or higher.** Max audio size: 10 MB (base64-encoded).","operationId":"createVoiceClone","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","audioData","mimeType"],"properties":{"name":{"type":"string","example":"My Voice"},"audioData":{"type":"string","format":"byte","description":"Base64-encoded audio sample."},"mimeType":{"type":"string","enum":["audio/wav","audio/mp3","audio/mpeg","audio/ogg","audio/webm"]}}}}}},"responses":{"200":{"description":"Voice clone created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceClone"}}}},"400":{"description":"Invalid audio data or size exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Pro plan required for voice cloning.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/voice/generate":{"post":{"tags":["Voice"],"summary":"Generate TTS audio from a voice clone","description":"Synthesizes speech using a cloned voice. Returns binary audio/wav.","operationId":"generateVoiceAudio","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","voiceId"],"properties":{"text":{"type":"string","example":"Welcome to our event!"},"voiceId":{"type":"string","description":"Convex voice clone ID."},"exaggeration":{"type":"number","minimum":0.25,"maximum":2,"description":"Overrides the clone's own setting for this clip."},"cfgWeight":{"type":"number","minimum":0,"maximum":1,"description":"Overrides the clone's own setting for this clip."}}}}}},"responses":{"200":{"description":"Audio file.","headers":{"X-Storage-Id":{"schema":{"type":"string"},"description":"Convex storage ID."},"X-Audio-Url":{"schema":{"type":"string"},"description":"CDN URL for the stored audio."}},"content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Missing text or voiceId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/voice/{id}":{"get":{"tags":["Voice"],"summary":"Get a voice clone","operationId":"getVoiceClone","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Voice clone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceClone"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Voice clone not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"patch":{"tags":["Voice"],"summary":"Set a voice clone's voice settings","description":"Every clip in this voice uses these settings unless a request overrides them. `null` resets a setting to 0.5.","operationId":"updateVoiceCloneSettings","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"exaggeration":{"type":"number","minimum":0.25,"maximum":2,"nullable":true},"cfgWeight":{"type":"number","minimum":0,"maximum":1,"nullable":true}}}}}},"responses":{"200":{"description":"The stored settings.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"voiceSettings":{"$ref":"#/components/schemas/VoiceSettings"}}}}}},"400":{"description":"No setting given, or one is out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Voice clone not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Voice"],"summary":"Delete a voice clone","description":"Deletes the voice the same way Voice Studio does. Its consent is revoked, its training is stopped and retired, and its training recordings are kept but no longer linked to it. Characters that speak with it switch to a stock voice. Embers already spent on it are not refunded. The voice disappears from every list and lookup and frees its clone slot. The voice's owner may delete it, and so may an owner or admin of the company whose brand it is shared into. Deleting a voice that is already deleted returns 204. Cannot delete clones with status `processing`.","operationId":"deleteVoiceClone","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted, or already deleted."},"400":{"description":"Cannot delete while processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Voice clone not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/brand/profiles":{"get":{"tags":["Brand"],"summary":"List brand profiles","operationId":"listBrandProfiles","responses":{"200":{"description":"Profile list.","content":{"application/json":{"schema":{"type":"object","properties":{"profiles":{"type":"array","items":{"$ref":"#/components/schemas/BrandProfile"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Brand"],"summary":"Create a brand profile","operationId":"createBrandProfile","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Main Brand"},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/Platform"}},"voice":{"type":"object","properties":{"tone":{"type":"string"},"style":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"avoidWords":{"type":"array","items":{"type":"string"}}}},"primaryColor":{"type":"string","example":"#FF5733"},"logoUrl":{"type":"string","format":"uri"},"isDefault":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Profile created.","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/BrandProfile"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/brand/profiles/{id}":{"get":{"tags":["Brand"],"summary":"Get a brand profile","operationId":"getBrandProfile","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Brand profile.","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/BrandProfile"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"patch":{"tags":["Brand"],"summary":"Update a brand profile","operationId":"updateBrandProfile","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/Platform"}},"voice":{"type":"object","properties":{"tone":{"type":"string"},"style":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"avoidWords":{"type":"array","items":{"type":"string"}}}},"primaryColor":{"type":"string"},"logoUrl":{"type":"string","format":"uri"},"isDefault":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated profile.","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/BrandProfile"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Brand"],"summary":"Delete a brand profile","operationId":"deleteBrandProfile","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/brand/analyze":{"post":{"tags":["Brand"],"summary":"Run AI brand analysis","description":"Analyzes brand profile, voice clones, content, and assets to generate strategic brand suggestions. Tier limits: free=1/month, pro=10/month, agency=unlimited.","operationId":"analyzeBrand","responses":{"200":{"description":"Brand analysis results.","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"suggestions":{"type":"object","properties":{"tagline":{"type":"string"},"toneAndStyle":{"type":"string"},"targetAudience":{"type":"string"},"contentPillars":{"type":"array","items":{"type":"string"}},"brandValues":{"type":"array","items":{"type":"string"}},"monthlyTips":{"type":"array","items":{"type":"string"}}}},"sourcesAnalyzed":{"type":"object","properties":{"assets":{"type":"integer"},"posts":{"type":"integer"},"voices":{"type":"integer"}}},"tier":{"type":"string","example":"pro"},"limit":{"type":"integer","nullable":true},"used":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Monthly analysis limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/brand/posting-times":{"get":{"tags":["Brand"],"summary":"Get best posting times","description":"Returns AI-recommended posting times based on brand demographics, Zernio analytics, and platform research.","operationId":"getBrandPostingTimes","parameters":[{"name":"platform","in":"query","schema":{"type":"string","enum":["instagram","twitter","linkedin","facebook","tiktok","youtube"],"default":"instagram"}},{"name":"timezone","in":"query","schema":{"type":"string","default":"UTC","example":"America/New_York"}},{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}}],"responses":{"200":{"description":"Posting time recommendations.","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"timezone":{"type":"string"},"recommendations":{"type":"array","items":{"type":"object","additionalProperties":true}},"heatmap":{"type":"object","additionalProperties":true},"meta":{"type":"object","properties":{"hasDemographics":{"type":"boolean"},"hasAnalytics":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/analytics":{"get":{"tags":["Analytics"],"summary":"Fetch analytics","description":"Returns engagement metrics from Zernio. Falls back to empty-but-valid response if Zernio is unavailable.","operationId":"getAnalytics","parameters":[{"name":"dateRange","in":"query","schema":{"type":"string","enum":["7d","30d","90d","custom"],"default":"30d"}},{"name":"platform","in":"query","schema":{"$ref":"#/components/schemas/Platform"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date"},"description":"Required when dateRange=custom."},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"},"description":"Required when dateRange=custom."}],"responses":{"200":{"description":"Analytics data.","content":{"application/json":{"schema":{"type":"object","properties":{"dateRange":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"mock":{"type":"boolean","nullable":true},"totals":{"type":"object","properties":{"impressions":{"type":"integer"},"reach":{"type":"integer"},"engagements":{"type":"integer"},"clicks":{"type":"integer"},"followers":{"type":"integer","nullable":true},"followerGrowth":{"type":"integer","nullable":true},"postsPublished":{"type":"integer"},"avgEngagementRate":{"type":"number"}}},"timeSeries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"impressions":{"type":"integer"},"reach":{"type":"integer"},"engagements":{"type":"integer"},"clicks":{"type":"integer"},"followers":{"type":"integer","nullable":true}}}},"platformBreakdown":{"type":"array","items":{"type":"object","additionalProperties":true}},"topPosts":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/analytics/google-business":{"get":{"tags":["Analytics"],"summary":"Google Business Profile performance","description":"Profile views (Search + Maps), searches (views from Google Search) and actions (calls, website clicks, directions, messages, bookings, food orders, menu clicks) for the GBP accounts of the active workspace, incl. accounts shared into the brand. Read live from Zernio, cached 10 minutes per account and range; nothing is stored.","operationId":"getGoogleBusinessPerformance","parameters":[{"name":"days","in":"query","schema":{"type":"integer","enum":[7,28,90],"default":28}},{"name":"accountId","in":"query","description":"Only this GBP account. Must belong to the active workspace (403 otherwise).","schema":{"type":"string"}}],"responses":{"200":{"description":"Per-account and total performance.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unsupported range."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"502":{"description":"Zernio account listing failed."}}}},"/api/video/compose":{"post":{"tags":["Video"],"summary":"Create a video composition job","description":"Creates an async video job. Poll `/api/video/status/{jobId}` for progress.","operationId":"createVideoCompose","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["backgroundType","audioType","textContent","overlayType"],"properties":{"backgroundType":{"type":"string","enum":["stock","ai","solid","upload"]},"backgroundUrl":{"type":"string","format":"uri","nullable":true},"backgroundColor":{"type":"string","nullable":true,"example":"#000000"},"audioUrl":{"type":"string","format":"uri","nullable":true},"audioType":{"type":"string","enum":["tts","recorded","none"]},"textContent":{"type":"string","example":"Join us for the event!"},"overlayType":{"type":"string","enum":["static","scrolling"]},"format":{"type":"string","enum":["9:16"],"default":"9:16"}}}}}},"responses":{"200":{"description":"Job created.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","example":"job_01HZ"},"composerJobId":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/VideoJobStatus"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/video/status/{jobId}":{"get":{"tags":["Video"],"summary":"Get video job status","operationId":"getVideoStatus","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/VideoJobStatus"},"renderedUrl":{"type":"string","format":"uri","nullable":true},"errorMessage":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Job not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/video/export/{jobId}":{"get":{"tags":["Video"],"summary":"Export a completed video","description":"Returns a download URL. Job must have status `completed`.","operationId":"exportVideo","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Download URL.","content":{"application/json":{"schema":{"type":"object","properties":{"downloadUrl":{"type":"string","format":"uri"}}}}}},"400":{"description":"Job not completed yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Job not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/queue":{"get":{"tags":["Social Queue"],"summary":"Get publishing queue","description":"Returns local Convex schedules plus Zernio posts and queue preview. Returns local-only if Zernio profile not connected.","operationId":"getSocialQueue","parameters":[{"name":"startDate","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Queue data.","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Zernio posts."},"queue":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Zernio queue preview."},"local":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Convex-local schedules."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"patch":{"tags":["Social Queue"],"summary":"Reschedule a queued post","operationId":"rescheduleQueuedPost","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["postId","scheduledFor"],"properties":{"postId":{"type":"string"},"scheduledFor":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["zernio","local"],"description":"`local` reschedules via Convex; omit for Zernio."}}}}}},"responses":{"200":{"description":"Rescheduled.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Missing fields or Zernio not connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/queue/slots":{"get":{"tags":["Social Queue"],"summary":"List queue slots","description":"Returns all named queues (per Zernio profile) with their time slots.","operationId":"listQueueSlots","responses":{"200":{"description":"Queue slots.","content":{"application/json":{"schema":{"type":"object","properties":{"queues":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Zernio profile not connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Social Queue"],"summary":"Create a queue or slot","description":"If `name` is provided, creates a named queue. Otherwise adds one slot `{ dayOfWeek, time }` to the caller's queue `queueId`. Zernio slots have no ids and queues are per profile, not per account.","operationId":"createQueueSlot","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Queue name (for queue creation).","example":"Morning Posts"},"timezone":{"type":"string","example":"America/New_York"},"slots":{"type":"array","items":{"type":"object","properties":{"dayOfWeek":{"type":"integer","minimum":0,"maximum":6},"time":{"type":"string","example":"09:00"}}}},"active":{"type":"boolean","default":true},"queueId":{"type":"string","description":"For adding one slot."},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Sunday. `day` (weekday name) is also accepted."},"time":{"type":"string","example":"09:00"}}}}}},"responses":{"200":{"description":"Queue or slot created.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"put":{"tags":["Social Queue"],"summary":"Update a queue or slot","description":"Updates the caller's queue `queueId` (404 if it is not in the caller's profile). Unspecified timezone/slots keep their current values. With `slot: { dayOfWeek, time }`, moves that one slot to the given `dayOfWeek`/`time`. `slotId` is rejected: Zernio slots have no ids.","operationId":"updateQueueSlot","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queueId":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"},"slots":{"type":"array","items":{"type":"object","additionalProperties":true}},"active":{"type":"boolean"},"setAsDefault":{"type":"boolean"},"reshuffleExisting":{"type":"boolean"},"slot":{"type":"object","properties":{"dayOfWeek":{"type":"integer"},"time":{"type":"string"}},"description":"The slot to move."},"dayOfWeek":{"type":"integer"},"time":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Missing queueId or slotId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Social Queue"],"summary":"Delete a queue or slot","description":"Deletes the caller's queue `queueId` (404 if it is not in the caller's profile), or only its slot `dayOfWeek` + `time` when given.","operationId":"deleteQueueSlot","parameters":[{"name":"queueId","in":"query","required":true,"schema":{"type":"string"},"description":"Queue to delete (or to delete a slot from)."},{"name":"dayOfWeek","in":"query","schema":{"type":"integer","minimum":0,"maximum":6},"description":"Slot to delete (with time)."},{"name":"time","in":"query","schema":{"type":"string","example":"09:00"},"description":"Slot to delete (with dayOfWeek)."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Missing queueId or slotId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/queue/preview":{"get":{"tags":["Social Queue"],"summary":"Preview upcoming queue slots","description":"Returns ISO timestamps for the next N scheduled slot times.","operationId":"previewQueue","parameters":[{"name":"count","in":"query","schema":{"type":"integer","default":10},"description":"Number of upcoming slots to preview."},{"name":"queueId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Preview slots.","content":{"application/json":{"schema":{"type":"object","properties":{"profileId":{"type":"string"},"count":{"type":"integer"},"slots":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Zernio profile not connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/best-times":{"get":{"tags":["Social Queue"],"summary":"Get best times to post","description":"Fetches best times from Zernio analytics. Requires Zernio profile to be connected.","operationId":"getSocialBestTimes","parameters":[{"name":"accountId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"$ref":"#/components/schemas/Platform"}}],"responses":{"200":{"description":"Best post times.","content":{"application/json":{"schema":{"type":"object","properties":{"bestTimes":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Zernio profile not connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/inbox":{"get":{"tags":["Social Inbox"],"summary":"List inbox conversations","description":"Returns Zernio-enriched conversation list with contact and read status data. Returns empty array if Zernio is not connected.","operationId":"listInboxConversations","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","closed","archived"]}},{"name":"platform","in":"query","schema":{"$ref":"#/components/schemas/Platform"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Conversations.","content":{"application/json":{"schema":{"type":"object","properties":{"conversations":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/inbox/{conversationId}":{"get":{"tags":["Social Inbox"],"summary":"Get conversation messages","operationId":"getInboxConversation","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Zernio account the conversation is on (from the conversation list). Must belong to the caller's profile; when omitted the server finds the conversation in the caller's inbox."},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":50}}],"responses":{"200":{"description":"Paginated messages.","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","additionalProperties":true}},"nextCursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Social Inbox"],"summary":"Send a message in a conversation","operationId":"sendInboxMessage","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","example":"Thanks for reaching out!"},"mediaUrl":{"type":"string","format":"uri","nullable":true},"accountId":{"type":"string","description":"Zernio account the conversation is on; must belong to the caller's profile."}}}}}},"responses":{"200":{"description":"Message sent.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"patch":{"tags":["Social Inbox"],"summary":"Update conversation status","operationId":"updateInboxConversation","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["open","closed","archived"],"description":"open → Zernio active; closed/archived → Zernio archived."},"accountId":{"type":"string","description":"Zernio account the conversation is on; must belong to the caller's profile."}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/inbox/{conversationId}/read":{"post":{"tags":["Social Inbox"],"summary":"Mark conversation as read","operationId":"markInboxRead","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lastReadMessageId":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Marked as read.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/mentions":{"get":{"tags":["Social Inbox"],"summary":"List mentions","description":"Read-only list of posts that mention the caller's connected accounts (Zernio currently returns LinkedIn organization mentions only). Scoped to the active workspace's Zernio profile; mentions on other accounts are never returned. Returns an empty array if Zernio is not connected.","operationId":"listInboxMentions","parameters":[{"name":"accountId","in":"query","description":"Only mentions of this connected account. Must belong to the caller.","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Mentions.","content":{"application/json":{"schema":{"type":"object","properties":{"mentions":{"type":"array","items":{"type":"object","additionalProperties":true}},"nextCursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/social/reviews":{"get":{"tags":["Social Inbox"],"summary":"List Google Business Profile reviews","description":"The inbox Reviews tab. Reviews of every Google Business Profile account the caller may access in the active workspace (Personal, brand, and accounts shared into the brand), read live from Zernio. Reviews on other accounts are never returned. Pro+ (inbox).","operationId":"listInboxReviews","parameters":[{"name":"accountId","in":"query","description":"Only this GBP account. Must belong to the active workspace (403 otherwise).","schema":{"type":"string"}},{"name":"unreplied","in":"query","description":"1 = only reviews without an owner reply.","schema":{"type":"string","enum":["1","true"]}},{"name":"lowRating","in":"query","description":"1 = only 1–2 star reviews.","schema":{"type":"string","enum":["1","true"]}},{"name":"cursor","in":"query","description":"Next page (single-account listings only).","schema":{"type":"string"}}],"responses":{"200":{"description":"Reviews.","content":{"application/json":{"schema":{"type":"object","properties":{"reviews":{"type":"array","items":{"type":"object","additionalProperties":true}},"accounts":{"type":"array","items":{"type":"object","additionalProperties":true}},"nextCursor":{"type":"string","nullable":true},"failedAccounts":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Inbox requires Pro."},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Social Inbox"],"summary":"Reply to a Google Business Profile review (or edit the reply)","description":"Posts the owner reply. Google keeps one reply per review, so replying to a replied review replaces (edits) it. The account must be a GBP account of the active workspace and the review must be in that account's own listing.","operationId":"replyToInboxReview","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reviewId","accountId","text"],"properties":{"reviewId":{"type":"string"},"accountId":{"type":"string"},"text":{"type":"string","maxLength":4096}}}}}},"responses":{"200":{"description":"Reply posted; returns the updated review.","content":{"application/json":{"schema":{"type":"object","properties":{"review":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Missing ids or text."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Inbox requires Pro."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Review not found on this account."},"502":{"description":"Zernio rejected the reply."}}},"delete":{"tags":["Social Inbox"],"summary":"Delete the owner reply on a Google Business Profile review","operationId":"deleteInboxReviewReply","parameters":[{"name":"reviewId","in":"query","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reply deleted; returns the updated review."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Review not found on this account."},"409":{"description":"The review has no reply."},"502":{"description":"Zernio rejected the delete."}}}},"/api/social/reviews/suggest-reply":{"post":{"tags":["Social Inbox"],"summary":"AI-suggested reply to a Google Business Profile review","description":"Drafts an owner reply in the brand voice from the review as Zernio lists it. Never posts. Costs 3 Embers per successful suggestion (nothing when it fails).","operationId":"suggestInboxReviewReply","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reviewId","accountId"],"properties":{"reviewId":{"type":"string"},"accountId":{"type":"string"}}}}}},"responses":{"200":{"description":"A draft.","content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"type":"string"},"alternatives":{"type":"array","items":{"type":"string"}},"tone":{"type":"string"},"credits":{"type":"integer","example":3}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Inbox requires Pro, or not enough Embers."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Review not found on this account."},"429":{"description":"Rate limited."}}}},"/api/social/comments":{"get":{"tags":["Social Comments"],"summary":"List comments","description":"Returns all inbox comments, or comments for a specific post.","operationId":"listComments","parameters":[{"name":"postId","in":"query","schema":{"type":"string"},"description":"Filter to a specific post (requires accountId)."},{"name":"accountId","in":"query","schema":{"type":"string"},"description":"Zernio account the post is on; must be on the caller's Personal profile, a brand they belong to, or shared into one of those brands."}],"responses":{"200":{"description":"Comments.","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"accountId is not one the caller may act on (their Personal profile, their brands, or accounts shared into those brands)."},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Social Comments"],"summary":"Reply to a comment or post","operationId":"replyToComment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["postId","accountId","text"],"properties":{"postId":{"type":"string"},"accountId":{"type":"string","description":"Zernio account to reply from; must be on the caller's Personal profile, a brand they belong to, or shared into one of those brands."},"commentId":{"type":"string","description":"Reply to this comment instead of the post."},"clientProfileId":{"type":"string","description":"Optional: the brand the comment is filed under, checked first. Grants nothing by itself."},"text":{"type":"string","example":"Thanks for the comment!"}}}}}},"responses":{"200":{"description":"Reply sent.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"accountId is not one the caller may act on (their Personal profile, their brands, or accounts shared into those brands)."},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Social Comments"],"summary":"Delete or hide a comment","operationId":"deleteComment","parameters":[{"name":"commentId","in":"query","required":true,"schema":{"type":"string"}},{"name":"postId","in":"query","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string"},"description":"Must be on the caller's Personal profile, a brand they belong to, or shared into one of those brands."},{"name":"action","in":"query","schema":{"type":"string","enum":["delete","hide"],"default":"delete"}}],"responses":{"200":{"description":"Deleted or hidden.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"accountId is not one the caller may act on (their Personal profile, their brands, or accounts shared into those brands)."},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/media/{id}":{"get":{"tags":["Media"],"summary":"Stream a media file","description":"Streams a media file from Convex storage. Validates ownership before returning.","operationId":"getMedia","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Convex media file document ID."}],"responses":{"200":{"description":"Binary media stream.","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Not the owner of this media.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Media not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/inference/tts":{"post":{"tags":["Inference"],"summary":"Generate text-to-speech audio","description":"Synthesizes speech from text. `auto` (default) uses flayr's own voice model. `elevenlabs` uses only the caller's own saved ElevenLabs key (BYOK); with no saved key it returns 403 `elevenlabs_key_required`, and ElevenLabs errors return 502. Google falls back to local on errors. Speech flayr makes costs Embers at the Voice Studio rates, priced by the speaker per 1,000 spoken characters (your cloned voice or a stock voice, from the live model pricing); a failed generation is refunded and BYOK ElevenLabs costs 0 Embers. The amount charged is returned in `X-Embers-Charged`.","operationId":"inferTts","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":5000,"example":"Welcome to our event!"},"language":{"type":"string","nullable":true,"example":"en-US"},"voiceId":{"type":"string","nullable":true,"description":"ElevenLabs voice ID or local clone ID."},"provider":{"type":"string","enum":["auto","local","elevenlabs","google"],"default":"auto","description":"`auto` = flayr's own voice model. `elevenlabs` requires the caller's own saved ElevenLabs key."}}}}}},"responses":{"200":{"description":"Audio stream.","headers":{"X-Embers-Charged":{"schema":{"type":"integer"},"description":"Embers charged for this speech (0 for BYOK)."},"Content-Disposition":{"schema":{"type":"string"},"description":"attachment; filename=speech.wav or speech.mp3"}},"content":{"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Missing or too-long text.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"`insufficient_credits`: not enough Embers for this script (`required`, `remaining`, `message`), or the Video Creator is not on the plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`elevenlabs_key_required`: provider `elevenlabs` asked for but the caller has no saved ElevenLabs key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Voice fair use: a speech job is still in progress, or the plan's monthly cloned-speech minutes are used up (`message`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"`elevenlabs_error`: ElevenLabs rejected the request made with the caller's key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/notifications":{"get":{"tags":["Notifications"],"summary":"List notifications","operationId":"listNotifications","responses":{"200":{"description":"Notifications.","content":{"application/json":{"schema":{"type":"object","properties":{"notifications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"read":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}},"patch":{"tags":["Notifications"],"summary":"Mark notification(s) as read","operationId":"markNotificationsRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"notificationId":{"type":"string","description":"Mark a single notification as read."},"markAllRead":{"type":"boolean","description":"Mark all notifications as read. Overrides notificationId."}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Neither notificationId nor markAllRead provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v2/ops/sample-deliveries":{"get":{"tags":["Ops: sample deliveries"],"security":[{"opsKeyAuth":[]}],"summary":"Find sample sources, customer brands, or delivery status","description":"The owner must sign in with super-admin access and open [Super Admin → Ops keys](/super-admin/ops-keys).\nUnder **Issue a key**, enter a name, select **admin:deliver-samples**, deselect **admin:flags** for a delivery-only agent,\nleave both flag and config allowlists empty, and click **Issue key**. Copy the key once into the operator agent's secret store.\nSend it as `Authorization: Bearer flayr_ops_…`; a staff session or customer API key cannot substitute for it.\nThe key stops working if revoked or if its issuer loses super-admin access.\n\nFirst configure a staff samples workspace at [/super-admin/sample-delivery](/super-admin/sample-delivery).\nChoose **Mark as internal and add** for an unmarked workspace; this enables the internal staff pass for members already marked internal,\nunless the workspace has a billing hold. Other members keep their plan access.\nAdd a campaign label to the sample brand's draft posts in Library and use the customer owner's exact sign-in email or Clerk user id.\n\nWithout deliveryId, returns sources and (when customer is supplied) customer and customerBrands. A null customer means no matching account: check the sign-in email or Clerk user id, or ask the owner to sign up. Empty sources: configure a samples workspace and create an active sample brand there. With deliveryId, returns the delivery, including status (copying, delivered, failed, removed), error and copiedCount. deliveryId takes precedence over customer.","parameters":[{"name":"customer","in":"query","schema":{"type":"string"},"description":"Customer owner’s exact sign-in email or Clerk user id."},{"name":"deliveryId","in":"query","schema":{"type":"string"},"description":"Id returned by POST; check this until delivered or failed."}],"responses":{"200":{"description":"JSON: { ok: true, sources, customer?, customerBrands? } or { ok: true, delivery }."},"400":{"description":"Invalid request or missing reason. Read error for the required fix."},"401":{"description":"Missing, invalid, revoked or orphaned ops key. The owner issues a key at /super-admin/ops-keys."},"403":{"description":"Required scope missing, or delivery refused. The JSON error names the fix; refusal names the delivery rule."},"404":{"description":"Delivery not found. Check deliveryId."},"429":{"description":"Rate limit exceeded."}}},"post":{"tags":["Ops: sample deliveries"],"security":[{"opsKeyAuth":[]}],"summary":"Deliver a sample campaign pending the customer owner’s approval","description":"The owner must sign in with super-admin access and open [Super Admin → Ops keys](/super-admin/ops-keys).\nUnder **Issue a key**, enter a name, select **admin:deliver-samples**, deselect **admin:flags** for a delivery-only agent,\nleave both flag and config allowlists empty, and click **Issue key**. Copy the key once into the operator agent's secret store.\nSend it as `Authorization: Bearer flayr_ops_…`; a staff session or customer API key cannot substitute for it.\nThe key stops working if revoked or if its issuer loses super-admin access.\n\nFirst configure a staff samples workspace at [/super-admin/sample-delivery](/super-admin/sample-delivery).\nChoose **Mark as internal and add** for an unmarked workspace; this enables the internal staff pass for members already marked internal,\nunless the workspace has a billing hold. Other members keep their plan access.\nAdd a campaign label to the sample brand's draft posts in Library and use the customer owner's exact sign-in email or Clerk user id.\n\nCopies one labeled campaign into the named customer’s own brand. Never publishes, approves or charges. Requires a reason and is audited under the key. A 200 starts the copy; GET with deliveryId confirms the final result. A missing label is refused: add the label to the sample brand’s draft posts in Library or select an existing label. Keep allowRepeat false unless intentionally delivering a second copy. Supplying setupRequestId also requires support:requests.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceClientProfileId","campaignLabel","targetClientProfileId","customer","reason"],"properties":{"sourceClientProfileId":{"type":"string","description":"Sample brand id from GET sources."},"campaignLabel":{"type":"string","example":"campaign:example-sample"},"targetClientProfileId":{"type":"string","description":"Brand owned by customer, from GET customerBrands."},"customer":{"type":"string","description":"Customer owner’s email or Clerk user id."},"reason":{"type":"string","description":"Required explanation for the audit log."},"dateShiftDays":{"type":"integer","default":0},"unscheduled":{"type":"boolean","default":false,"description":"Deliver without planned times; the owner chooses them."},"allowRepeat":{"type":"boolean","default":false},"setupRequestId":{"type":"string","description":"Optional set-up request id; also needs support:requests."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, deliveryId, groupId, postCount, status: \"copying\" }. Not yet delivered."},"400":{"description":"Invalid request or missing reason. Read error for the required fix."},"401":{"description":"Missing, invalid, revoked or orphaned ops key. The owner issues a key at /super-admin/ops-keys."},"403":{"description":"Required scope missing, or delivery refused. The JSON error names the fix; refusal names the delivery rule."},"429":{"description":"Rate limit exceeded."}}}},"/api/v2/ops/landing-variant":{"get":{"tags":["Ops: staff switches"],"security":[{"opsKeyAuth":[]}],"summary":"Read the landing A/B split","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) and selects only the scopes the agent needs.\nSend it as `Authorization: Bearer flayr_ops_…`. The key stops working if revoked or if its issuer loses super-admin access.\nEvery change needs a reason, writes a superAdminAuditLogs row naming the key and the super-admin who issued it, and notifies every super-admin.\nMoney switches (deals, prices, coupons, billing flags) are not reachable here; billing flags need the separate ops:money scope on the flags route.\n\nNeeds scope ops:landing.","responses":{"200":{"description":"JSON: { ok: true, config: { variants, promoted, paused } }."},"400":{"description":"Invalid request, a value the super-admin page would also refuse, or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the required scope. A super-admin can add it at /super-admin/ops-keys."},"429":{"description":"Rate limit exceeded."}}},"post":{"tags":["Ops: staff switches"],"security":[{"opsKeyAuth":[]}],"summary":"Replace the landing A/B split","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) and selects only the scopes the agent needs.\nSend it as `Authorization: Bearer flayr_ops_…`. The key stops working if revoked or if its issuer loses super-admin access.\nEvery change needs a reason, writes a superAdminAuditLogs row naming the key and the super-admin who issued it, and notifies every super-admin.\nMoney switches (deals, prices, coupons, billing flags) are not reachable here; billing flags need the separate ops:money scope on the flags route.\n\nNeeds scope ops:landing. Same validation as /super-admin/landing-variant: weights 0-100, promoted sends everyone to one arm, paused stops new assignment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["variants","reason"],"properties":{"variants":{"type":"array","items":{"type":"object","required":["id","weight"],"properties":{"id":{"type":"string","enum":["current","v4"]},"weight":{"type":"number"}}}},"promoted":{"type":"string","enum":["current","v4"],"nullable":true,"description":"Send everyone to one arm; null to split."},"paused":{"type":"boolean","default":false},"reason":{"type":"string","description":"Required explanation for the audit log."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, before, config }."},"400":{"description":"Invalid request, a value the super-admin page would also refuse, or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the required scope. A super-admin can add it at /super-admin/ops-keys."},"429":{"description":"Rate limit exceeded."}}}},"/api/v2/ops/booking-gate":{"get":{"tags":["Ops: staff switches"],"security":[{"opsKeyAuth":[]}],"summary":"Read one workspace’s or brand’s booking-gate override","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) and selects only the scopes the agent needs.\nSend it as `Authorization: Bearer flayr_ops_…`. The key stops working if revoked or if its issuer loses super-admin access.\nEvery change needs a reason, writes a superAdminAuditLogs row naming the key and the super-admin who issued it, and notifies every super-admin.\nMoney switches (deals, prices, coupons, billing flags) are not reachable here; billing flags need the separate ops:money scope on the flags route.\n\nNeeds scope ops:booking-gate. Returns the stored override (null when none) and the config it resolves to.","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["workspace","brand"]}},{"name":"ownerId","in":"query","required":true,"schema":{"type":"string"},"description":"Workspace: the owner’s Clerk user id. Brand: the brand id."}],"responses":{"200":{"description":"JSON: { ok: true, scope, ownerId, override, effective }."},"400":{"description":"Invalid request, a value the super-admin page would also refuse, or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the required scope. A super-admin can add it at /super-admin/ops-keys."},"404":{"description":"No workspace or brand with that id."},"429":{"description":"Rate limit exceeded."}}},"post":{"tags":["Ops: staff switches"],"security":[{"opsKeyAuth":[]}],"summary":"Replace or reset one booking-gate override","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) and selects only the scopes the agent needs.\nSend it as `Authorization: Bearer flayr_ops_…`. The key stops working if revoked or if its issuer loses super-admin access.\nEvery change needs a reason, writes a superAdminAuditLogs row naming the key and the super-admin who issued it, and notifies every super-admin.\nMoney switches (deals, prices, coupons, billing flags) are not reachable here; billing flags need the separate ops:money scope on the flags route.\n\nNeeds scope ops:booking-gate. Omitted fields inherit the defaults; reset: true removes the override. Same validation as /super-admin.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scope","ownerId","reason"],"properties":{"scope":{"type":"string","enum":["workspace","brand"]},"ownerId":{"type":"string"},"dupWindowDays":{"type":"number"},"minRepostGapDays":{"type":"number"},"platformDailyCaps":{"type":"object","additionalProperties":{"type":"number"}},"allowedAccountIds":{"type":"array","items":{"type":"string"}},"deadDestinationPolicy":{"type":"string","enum":["swap_or_hold","hold","off"]},"deadDestinationNoticeHours":{"type":"number"},"deadAccountRepairEnabled":{"type":"boolean"},"deadAccountRepairMaxPosts":{"type":"number"},"reset":{"type":"boolean"},"reason":{"type":"string","description":"Required explanation for the audit log."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, scope, ownerId, before, override }."},"400":{"description":"Invalid request, a value the super-admin page would also refuse, or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the required scope. A super-admin can add it at /super-admin/ops-keys."},"404":{"description":"No workspace or brand with that id."},"429":{"description":"Rate limit exceeded."}}}},"/api/v2/ops/help-videos":{"get":{"tags":["Ops: help videos"],"security":[{"opsKeyAuth":[]}],"summary":"List live help-center videos","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the ops:help scope.\nSend it as `Authorization: Bearer flayr_ops_…`. A video attached here shows on its feature page, in the help dock, on /help/how-to (with howToKey) and in the in-app tutorial step on the next read, with no deploy.","parameters":[{"name":"featureSlug","in":"query","required":false,"schema":{"type":"string"},"description":"One feature, e.g. campaign-builder."}],"responses":{"200":{"description":"JSON: { ok: true, videos: [{ id, featureSlug, section, kind, howToKey, title, link, youtubeId, hidden, createdAt }] }."},"400":{"description":"Invalid request (unknown feature, section or how-to slot, bad link) or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the ops:help scope."},"429":{"description":"Rate limit exceeded."}}},"post":{"tags":["Ops: help videos"],"security":[{"opsKeyAuth":[]}],"summary":"Attach a tutorial video to a feature section","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the ops:help scope.\nSend it as `Authorization: Bearer flayr_ops_…`. A video attached here shows on its feature page, in the help dock, on /help/how-to (with howToKey) and in the in-app tutorial step on the next read, with no deploy.\n\nA video already live on that feature answers 200 with alreadyPresent: true and adds nothing. An official or how-to slot that already shows a video answers 409 SLOT_TAKEN; resend with replace: true to keep the old video as a community video. Audited; super-admins are notified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["featureSlug","link","title","reason"],"properties":{"featureSlug":{"type":"string"},"section":{"type":"string","description":"Feature section id; default the first section (or the how-to slot’s)."},"kind":{"type":"string","enum":["official","community"],"default":"official"},"link":{"type":"string","description":"https link, usually a public YouTube URL."},"title":{"type":"string","maxLength":120},"howToKey":{"type":"string","description":"A /help/how-to slot key."},"durationSec":{"type":"number"},"replace":{"type":"boolean","default":false},"reason":{"type":"string","description":"Required explanation for the audit log."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, alreadyPresent, video, demoted }."},"400":{"description":"Invalid request (unknown feature, section or how-to slot, bad link) or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the ops:help scope."},"409":{"description":"SLOT_TAKEN: the official or how-to slot already shows a video."},"429":{"description":"Rate limit exceeded."}}}},"/api/v2/ops/invites":{"get":{"tags":["Ops: support"],"security":[{"opsKeyAuth":[]}],"summary":"Invite plans and pending invites","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the scope named below.\nSend it as `Authorization: Bearer flayr_ops_…`. Every change needs a reason, is audited and notifies super-admins. None of these calls charges a customer or writes to Stripe or Autumn billing.\n\nScope: support:invites.","responses":{"200":{"description":"JSON: { ok: true, plans, defaultDurationDays, pending, invitations, invitationsError? }."},"400":{"description":"Invalid request or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the support:invites scope."},"429":{"description":"Rate limit exceeded."}}},"post":{"tags":["Ops: support"],"security":[{"opsKeyAuth":[]}],"summary":"Invite an email with a time-boxed comp plan","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the scope named below.\nSend it as `Authorization: Bearer flayr_ops_…`. Every change needs a reason, is audited and notifies super-admins. None of these calls charges a customer or writes to Stripe or Autumn billing.\n\nScope: support:invites. Same rules as the super-admin invite form: plans enabled in the invite config, 1-366 days, refused for staff and existing accounts. The comp applies when the person signs up.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","plan","reason"],"properties":{"email":{"type":"string"},"plan":{"type":"string","description":"A plan id from GET, e.g. pro."},"durationDays":{"type":"integer","minimum":1,"maximum":366},"mode":{"type":"string","enum":["email","link"],"default":"email","description":"email sends Clerk's invite email; link returns a sign-up link."},"reason":{"type":"string","description":"Required explanation for the audit log."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, grantId, invitation: { id, mode, url? } }."},"400":{"description":"Invalid request or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the support:invites scope."},"409":{"description":"REFUSED: the rules do not allow it (see error)."},"429":{"description":"Rate limit exceeded."}}},"delete":{"tags":["Ops: support"],"security":[{"opsKeyAuth":[]}],"summary":"Revoke a pending invite","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the scope named below.\nSend it as `Authorization: Bearer flayr_ops_…`. Every change needs a reason, is audited and notifies super-admins. None of these calls charges a customer or writes to Stripe or Autumn billing.\n\nScope: support:invites. Revokes the comp plan grant and the Clerk invitation (by email or invitationId).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"email":{"type":"string"},"invitationId":{"type":"string"},"reason":{"type":"string","description":"Required explanation for the audit log."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, grantRevoked, invitationRevoked, email, invitationId }."},"400":{"description":"Invalid request or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the support:invites scope."},"404":{"description":"NOT_FOUND: no such account, invite or workspace."},"429":{"description":"Rate limit exceeded."}}}},"/api/v2/ops/accounts":{"get":{"tags":["Ops: support"],"security":[{"opsKeyAuth":[]}],"summary":"Look up one account by email","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the scope named below.\nSend it as `Authorization: Bearer flayr_ops_…`. Every change needs a reason, is audited and notifies super-admins. None of these calls charges a customer or writes to Stripe or Autumn billing.\n\nScope: support:accounts. Read only; the lookup itself is audited.","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string"}},{"name":"reason","in":"query","required":false,"schema":{"type":"string"},"description":"Why you are looking, e.g. the support ticket."}],"responses":{"200":{"description":"JSON: { ok: true, account, inviteGrants, workspaces, brands, connectedAccounts, recentPosts, recentPlanChanges }."},"400":{"description":"Invalid request or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the support:accounts scope."},"404":{"description":"NOT_FOUND: no such account, invite or workspace."},"429":{"description":"Rate limit exceeded."}}},"post":{"tags":["Ops: support"],"security":[{"opsKeyAuth":[]}],"summary":"Set or extend a time-boxed comp","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the scope named below.\nSend it as `Authorization: Bearer flayr_ops_…`. Every change needs a reason, is audited and notifies super-admins. None of these calls charges a customer or writes to Stripe or Autumn billing.\n\nScope: support:accounts. Ends at endsAt or after durationDays (send one; at most 366 days). The account returns to its own plan when the comp ends. Refused for staff, paid or billing-issue accounts, permanent comps and org plans.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","plan","reason"],"properties":{"email":{"type":"string"},"plan":{"type":"string","enum":["starter","pro","premium"]},"durationDays":{"type":"integer","minimum":1,"maximum":366},"endsAt":{"type":"string","description":"ISO date or epoch ms."},"reason":{"type":"string","description":"Required explanation for the audit log."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, account: { clerkId, email, plan, comp } }."},"400":{"description":"Invalid request or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the support:accounts scope."},"404":{"description":"NOT_FOUND: no such account, invite or workspace."},"409":{"description":"REFUSED: the rules do not allow it (see error)."},"429":{"description":"Rate limit exceeded."}}}},"/api/v2/ops/samples-workspaces":{"get":{"tags":["Ops: support"],"security":[{"opsKeyAuth":[]}],"summary":"Samples workspaces and staff-owned candidates","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the scope named below.\nSend it as `Authorization: Bearer flayr_ops_…`. Every change needs a reason, is audited and notifies super-admins. None of these calls charges a customer or writes to Stripe or Autumn billing.\n\nScope: support:samples-setup.","responses":{"200":{"description":"JSON: { ok: true, max, samplesBrandLimit, samplesWorkspaces, candidates }."},"400":{"description":"Invalid request or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the support:samples-setup scope."},"429":{"description":"Rate limit exceeded."}}},"post":{"tags":["Ops: support"],"security":[{"opsKeyAuth":[]}],"summary":"List a workspace as a samples workspace","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the scope named below.\nSend it as `Authorization: Bearer flayr_ops_…`. Every change needs a reason, is audited and notifies super-admins. None of these calls charges a customer or writes to Stripe or Autumn billing.\n\nScope: support:samples-setup. The workspace must be internal; markInternal: true marks it only when its owner and every member are staff. Customer workspaces are refused.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orgId","reason"],"properties":{"orgId":{"type":"string"},"markInternal":{"type":"boolean","default":false},"reason":{"type":"string","description":"Required explanation for the audit log."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, alreadyListed, markedInternal, workspace }."},"400":{"description":"Invalid request or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the support:samples-setup scope."},"404":{"description":"NOT_FOUND: no such account, invite or workspace."},"409":{"description":"REFUSED: the rules do not allow it (see error)."},"429":{"description":"Rate limit exceeded."}}},"delete":{"tags":["Ops: support"],"security":[{"opsKeyAuth":[]}],"summary":"Unlist a samples workspace","description":"A super-admin issues the key at [Super Admin → Ops keys](/super-admin/ops-keys) with the scope named below.\nSend it as `Authorization: Bearer flayr_ops_…`. Every change needs a reason, is audited and notifies super-admins. None of these calls charges a customer or writes to Stripe or Autumn billing.\n\nScope: support:samples-setup.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orgId","reason"],"properties":{"orgId":{"type":"string"},"reason":{"type":"string","description":"Required explanation for the audit log."}}}}}},"responses":{"200":{"description":"JSON: { ok: true, removed, workspace }."},"400":{"description":"Invalid request or a missing reason."},"401":{"description":"Missing, invalid, revoked or orphaned ops key."},"403":{"description":"The key lacks the support:samples-setup scope."},"404":{"description":"NOT_FOUND: no such account, invite or workspace."},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/generate/text":{"post":{"tags":["v1 / Generation"],"summary":"Generate text (v1)","operationId":"v1GenerateText","security":[{"bearerAuth":[]}],"x-credit-cost":"1-5 Embers per request (varies by model)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"Write a launch tweet about our new product."},"model":{"type":"string","description":"Text model id. Omitted: the default model. An unknown id returns 400 listing the available ids; a model above the plan returns 403 `tier_insufficient`."}}}}}},"responses":{"200":{"description":"Generated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"text":{"type":"string"},"model":{"type":"string"},"finishReason":{"type":"string","example":"stop"},"usage":{"type":"object","description":"Token usage reported by the model provider (inputTokens, outputTokens, totalTokens)."}}},"credits":{"type":"object","properties":{"used":{"type":"integer","description":"Embers charged."},"remaining":{"type":"integer","description":"Embers left after the charge."},"model":{"type":"string"}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."},"X-Credits-Used":{"schema":{"type":"integer"},"description":"Embers charged for this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Embers left in the pool the charge drew from."}}},"400":{"description":"Invalid JSON body, or a missing/invalid field.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"402":{"description":"Insufficient Embers to complete the request (checked before anything is generated).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Insufficient Embers. Required: 4, remaining: 2"},"credits":{"type":"object","properties":{"required":{"type":"integer"},"remaining":{"type":"integer"},"available":{"type":"integer"}}}}}}}},"403":{"description":"The plan does not include the requested model (`tier_insufficient`), or the plan has no API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"tier_insufficient"},"requiredFor":{"type":"string","description":"The model that was refused."}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Generation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"503":{"description":"The model's provider is not configured, or API key validation is unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/generate/image":{"post":{"tags":["v1 / Generation"],"summary":"Generate an image (v1)","operationId":"v1GenerateImage","security":[{"bearerAuth":[]}],"x-credit-cost":"10-125 Embers per image (varies by model)","description":"Generates one image and saves it to the key owner's Library. Synchronous: the response carries the hosted image URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"A minimal geometric pattern in cyan and purple."},"aspectRatio":{"type":"string","enum":["1:1","16:9","9:16","4:5"],"default":"1:1"},"model":{"type":"string","description":"Image model id. Omitted: the default image model."}}}}}},"responses":{"200":{"description":"Generated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"imageUrl":{"type":"string","format":"uri"},"prompt":{"type":"string","description":"The prompt the image was generated from."},"aspectRatio":{"type":"string"},"model":{"type":"string"}}},"credits":{"type":"object","properties":{"used":{"type":"integer","description":"Embers charged."},"remaining":{"type":"integer","description":"Embers left after the charge."},"model":{"type":"string"}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."},"X-Credits-Used":{"schema":{"type":"integer"},"description":"Embers charged for this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Embers left in the pool the charge drew from."}}},"400":{"description":"Invalid JSON body, or a missing/invalid field.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"402":{"description":"Insufficient Embers to complete the request (checked before anything is generated).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Insufficient Embers. Required: 4, remaining: 2"},"credits":{"type":"object","properties":{"required":{"type":"integer"},"remaining":{"type":"integer"}}}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Generation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/generate/video":{"post":{"tags":["v1 / Generation"],"summary":"Start a video clip generation (v1)","operationId":"v1GenerateVideo","security":[{"bearerAuth":[]}],"x-credit-cost":"390-1200 Embers per 6s clip (65-200 Embers/sec × duration)","description":"Generates a clip on the model for the key owner's plan, as the key owner, and returns its job. Works with the API key alone. The request waits for the clip (up to a few minutes); `videoUrl` is set when it is done and the clip also lands in the key owner's Library. Embers are reserved up front and refunded if generation fails (500 with `jobId`/`statusUrl`). `statusUrl` is GET /api/v1/generate/status/{jobId}, which takes the same API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"duration":{"type":"integer","enum":[4,6,8],"default":6,"description":"Clip length in seconds; other values snap to the nearest supported length."},"audio":{"description":"Native audio & dialogue for models that generate their own soundtrack through the AI Gateway (Veo 3.x, Seedance 2.x, Kling 3.0, FLUX 3 Video, MiniMax H3, Grok Imagine 1.5). `true`/`false` or an object. Dialogue is spoken in the model's own voice, not a cloned one, and is trimmed to about 2.5 words per second of clip. Omitted = the model's default. Ignored by models without native audio. Veo 3.1 Fast with audio on costs 75 Embers per second instead of 50.","oneOf":[{"type":"boolean"},{"type":"object","properties":{"enabled":{"type":"boolean","description":"Native audio on/off. Off unless set to true (opt-in; dialogue and hints are ignored without it)."},"dialogue":{"type":"string","maxLength":600,"description":"Lines to be spoken (dialogue or narration)."},"voiceHint":{"type":"string","maxLength":200,"example":"woman in her 30s, warm and confident"},"soundHint":{"type":"string","maxLength":200,"example":"soft rain, distant city traffic"}}}]}}}}}},"responses":{"200":{"description":"Generated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"jobId":{"type":"string","example":"job_1759000000000_ab12cd3"},"status":{"type":"string","enum":["processing","completed"],"example":"completed"},"prompt":{"type":"string"},"duration":{"type":"integer"},"model":{"type":"string"},"videoUrl":{"type":"string","nullable":true,"format":"uri"},"generateAudio":{"type":"boolean","description":"The native-audio switch sent to the model (absent = model default)."},"hasAudio":{"type":"boolean","description":"Whether the returned file has an audio track (checked from the file)."},"audioWarnings":{"type":"array","items":{"type":"string"}},"statusUrl":{"type":"string","example":"/api/v1/generate/status/{jobId}"}}},"credits":{"type":"object","properties":{"used":{"type":"integer","description":"Embers charged."},"remaining":{"type":"integer","description":"Embers left after the charge."},"model":{"type":"string"}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."},"X-Credits-Used":{"schema":{"type":"integer"},"description":"Embers charged for this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Embers left in the pool the charge drew from."}}},"400":{"description":"Invalid JSON body, or a missing/invalid field.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"402":{"description":"Insufficient Embers to complete the request (checked before anything is generated).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Insufficient Embers. Required: 4, remaining: 2"},"credits":{"type":"object","properties":{"required":{"type":"integer"},"remaining":{"type":"integer"}}}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Generation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/generate/caption":{"post":{"tags":["v1 / Generation"],"summary":"Generate a social caption (v1)","operationId":"v1GenerateCaption","security":[{"bearerAuth":[]}],"x-credit-cost":"1-5 Embers per request (text model weights)","description":"Writes one caption for a platform, aware of its character limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"Topic or brief for the caption."},"platform":{"type":"string","default":"instagram","example":"linkedin"},"model":{"type":"string","description":"Text model id. Omitted: the default model. An unknown id returns 400 listing the available ids; a model above the plan returns 403 `tier_insufficient`."},"hashtags":{"type":"boolean","default":true,"description":"Include 3-5 hashtags."}}}}}},"responses":{"200":{"description":"Generated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"caption":{"type":"string"},"platform":{"type":"string"},"charCount":{"type":"integer"},"charLimit":{"type":"integer"},"overLimit":{"type":"boolean"},"model":{"type":"string"}}},"credits":{"type":"object","properties":{"used":{"type":"integer","description":"Embers charged."},"remaining":{"type":"integer","description":"Embers left after the charge."},"model":{"type":"string"}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."},"X-Credits-Used":{"schema":{"type":"integer"},"description":"Embers charged for this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Embers left in the pool the charge drew from."}}},"400":{"description":"Invalid JSON body, or a missing/invalid field.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"402":{"description":"Insufficient Embers to complete the request (checked before anything is generated).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Insufficient Embers. Required: 4, remaining: 2"}}}}}},"403":{"description":"The plan does not include the requested model (`tier_insufficient`), or the plan has no API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"tier_insufficient"},"requiredFor":{"type":"string","description":"The model that was refused."}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Generation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"503":{"description":"The model's provider is not configured, or API key validation is unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/generate/voice":{"post":{"tags":["v1 / Generation"],"summary":"Generate voice audio (v1)","operationId":"v1GenerateVoice","security":[{"bearerAuth":[]}],"x-credit-cost":"4 (stock voice) or 15 (cloned voice) Embers per 1,000 characters of script (min 1)","description":"Synthesises speech from text with one of the key owner's voice clones, as the key owner. Works with the API key alone. The request waits for the audio and returns `audioUrl`; the job can also be read at `statusUrl` (GET /api/v1/generate/status/{jobId}, same API key). Returns 503 where voice generation is not available.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"voiceId":{"type":"string","description":"A voice clone id. Omitted: the key owner's newest ready voice clone (400 when they have none)."},"style":{"type":"string","enum":["natural","professional","casual","energetic"],"default":"natural"},"exaggeration":{"type":"number","minimum":0.25,"maximum":2,"description":"Expressiveness. Overrides the voice clone's own setting (default 0.5)."},"cfgWeight":{"type":"number","minimum":0,"maximum":1,"description":"Pacing. Overrides the voice clone's own setting (default 0.5)."}}}}}},"responses":{"200":{"description":"Generated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","example":"completed"},"audioUrl":{"type":"string","nullable":true,"format":"uri"},"text":{"type":"string"},"style":{"type":"string"},"voiceId":{"type":"string"},"model":{"type":"string"},"statusUrl":{"type":"string","example":"/api/v1/generate/status/{jobId}"}}},"credits":{"type":"object","properties":{"used":{"type":"integer","description":"Embers charged."},"remaining":{"type":"integer","description":"Embers left after the charge."},"model":{"type":"string"}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."},"X-Credits-Used":{"schema":{"type":"integer"},"description":"Embers charged for this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Embers left in the pool the charge drew from."}}},"400":{"description":"Invalid JSON body, or a missing/invalid field.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"402":{"description":"Insufficient Embers to complete the request (checked before anything is generated).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Insufficient Embers. Required: 4, remaining: 2"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Generation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"503":{"description":"Voice generation is not available on this environment, or API key validation is unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/generate/status/{jobId}":{"get":{"tags":["v1 / Generation"],"summary":"Status of a video or voice job (v1)","operationId":"v1GetGenerationJobStatus","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","description":"The `statusUrl` returned by POST /api/v1/generate/video and /api/v1/generate/voice. Takes the same API key; only the key owner's own jobs (or their org's shared jobs) resolve.","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The job.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"jobId":{"type":"string"},"type":{"type":"string","example":"video"},"status":{"type":"string","enum":["pending","processing","completed","error"]},"result":{"type":"object","nullable":true,"description":"`{ videoUrl }` or `{ audioUrl, storageId }` once completed."},"error":{"type":"string","nullable":true},"createdAt":{"type":"integer"},"completedAt":{"type":"integer","nullable":true}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"400":{"description":"Missing jobId.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"404":{"description":"No job with this id belongs to the key owner.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"The job could not be looked up.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/usage":{"get":{"tags":["v1 / Account"],"summary":"Usage counters for the current period (v1)","operationId":"v1GetUsage","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","responses":{"200":{"description":"The key owner's usage counters.","content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","example":"pro"},"period":{"type":"string","example":"2026-09"},"counters":{"type":"object","properties":{"textGenerations":{"type":"integer"},"imageGenerations":{"type":"integer"},"videoGenerations":{"type":"integer"},"voiceGenerations":{"type":"integer"},"socialPosts":{"type":"integer"},"apiCalls":{"type":"integer"}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/seats/limit":{"get":{"tags":["v1 / Account"],"summary":"Team seat cap + availability for the caller’s tier (v1)","operationId":"v1GetSeatLimit","description":"Returns the team seat cap for the current subscription tier + the `canInvite` flag the /team invitation UI uses to enable or block sends. Enterprise tiers return `seatsLimit: null` + `unlimited: true`.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","responses":{"200":{"description":"Seat availability report for the caller.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"tier":{"type":"string","example":"org_team"},"seatsLimit":{"type":"number","nullable":true,"example":5,"description":"null for unlimited enterprise tiers"},"seatsUsed":{"type":"number","example":0},"remaining":{"type":"number","nullable":true,"example":5},"canInvite":{"type":"boolean","example":true},"unlimited":{"type":"boolean","example":false}}}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/sequences/step-types":{"get":{"tags":["v1 / Sequences"],"summary":"Discover the canonical set of sequence step types (v1)","operationId":"v1ListSequenceStepTypes","description":"Returns every step type the sequence builder + Convex executor understand (FIR-1875). Each entry carries its label, icon, description, config field spec, and an `enabledInV0` flag so API callers know which types the v0 runtime already handles vs which are catalogued for future wire-up.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","responses":{"200":{"description":"Canonical sequence step type catalogue.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"count":{"type":"number","example":7},"v0EnabledIds":{"type":"array","items":{"type":"string"},"example":["send_message","add_tag","remove_tag"]},"stepTypes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"send_message"},"label":{"type":"string","example":"Send message"},"icon":{"type":"string","example":"MessageSquare"},"description":{"type":"string"},"blocksTimeline":{"type":"boolean","example":false},"branches":{"type":"boolean","example":false},"enabledInV0":{"type":"boolean","example":true},"fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["text","textarea","number","select","url"]},"placeholder":{"type":"string","nullable":true},"required":{"type":"boolean"},"options":{"type":"array","nullable":true,"items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}}}}}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/integrations/registry":{"get":{"tags":["v1 / Monitoring"],"summary":"Discover the canonical Flayr integration registry (v1)","operationId":"v1ListIntegrationRegistry","description":"Returns the canonical catalogue of every external service Flayr depends on (FIR-1781). Each entry carries its id, displayName, category (flayr/platform/ai/storage/observability), probeType, optional probeUrl, expectedSlaMs, and a publicFacing flag. The eventual public status page reads this catalogue + live `healthChecks` rows; this discovery endpoint is the pure-data layer.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","parameters":[{"name":"category","in":"query","required":false,"description":"Filter to a single category. One of flayr|platform|ai|storage|observability.","schema":{"type":"string"}},{"name":"publicOnly","in":"query","required":false,"description":"When `true`, only return integrations that should appear on the public status page.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Canonical integration registry, optionally filtered.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"count":{"type":"number","example":18},"totalKnown":{"type":"number","example":18},"publicCount":{"type":"number","example":9},"appliedFilters":{"type":"object","properties":{"category":{"type":"string","nullable":true},"publicOnly":{"type":"boolean"}}},"integrations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"clerk-api"},"displayName":{"type":"string","example":"Clerk Auth"},"category":{"type":"string","enum":["flayr","platform","ai","storage","observability"]},"probeType":{"type":"string"},"probeUrl":{"type":"string","nullable":true},"expectedSlaMs":{"type":"number","example":800},"publicFacing":{"type":"boolean"},"notes":{"type":"string","nullable":true}}}}}}}}}}},"400":{"description":"Invalid category filter."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/accounts/reactivation-preview":{"get":{"tags":["v1 / Account"],"summary":"Preview an account reactivation plan for a tier upgrade (v1)","operationId":"v1PreviewAccountReactivation","description":"Pure read-only preview of which deactivated social accounts would be reactivated when a user upgrades from `oldTier` to `newTier` (FIR-1890). The accounts list is provided by the caller via the `accounts` query param so this endpoint never reads live Convex state. The eventual Autumn `subscription.updated` webhook will share the same planner helper for the actual reactivation.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","parameters":[{"name":"oldTier","in":"query","required":true,"schema":{"type":"string"},"example":"pro"},{"name":"newTier","in":"query","required":true,"schema":{"type":"string"},"example":"agency"},{"name":"accounts","in":"query","required":false,"description":"JSON-encoded array of `SocialAccountSnapshot` objects ({id, platform, active, createdAt, tokenExpired?}).","schema":{"type":"string"}}],"responses":{"200":{"description":"Reactivation plan + optional toast message.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"oldTier":{"type":"string","example":"pro"},"newTier":{"type":"string","example":"agency"},"toastMessage":{"type":"string","nullable":true},"plan":{"type":"object","properties":{"isUpgrade":{"type":"boolean"},"oldCap":{"type":"number"},"newCap":{"type":"number"},"extraSlots":{"type":"number"},"toReactivate":{"type":"array","items":{"type":"string"}},"toLeaveDeactivated":{"type":"array","items":{"type":"string"}},"needsReconnect":{"type":"array","items":{"type":"string"}},"alreadyActive":{"type":"array","items":{"type":"string"}}}}}}}}}}},"400":{"description":"Missing or invalid oldTier/newTier/accounts param."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tiers/upsell-analysis":{"get":{"tags":["v1 / Account"],"summary":"Per-tier credit affordability + upsell breakdown (FIR-1923)","operationId":"v1GetTierUpsellAnalysis","description":"Research-as-code endpoint exposing the FIR-1923 tier affordability analysis. Returns one row per Tier in the catalogue with monthlyCredits, per-modality affordability (videos / images / captions / voices), a headroom string, and an upsell hint pointing at the next tier in the same ladder. Optional `textCost` / `imageCost` / `videoCost` / `voiceCost` query params let the caller override the modality cost model so the founder + super-admin can run scenarios without redeploying.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","parameters":[{"name":"textCost","in":"query","required":false,"description":"Override average text-modality cost (credits per request).","schema":{"type":"number"}},{"name":"imageCost","in":"query","required":false,"description":"Override average image-modality cost (credits per image).","schema":{"type":"number"}},{"name":"videoCost","in":"query","required":false,"description":"Override average video-modality cost (credits per clip).","schema":{"type":"number"}},{"name":"voiceCost","in":"query","required":false,"description":"Override average voice-modality cost (credits per request).","schema":{"type":"number"}}],"responses":{"200":{"description":"Tier affordability + upsell analysis table.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"count":{"type":"number","example":7},"costs":{"type":"object","properties":{"text":{"type":"number"},"image":{"type":"number"},"video":{"type":"number"},"voice":{"type":"number"}}},"defaultCosts":{"type":"object","properties":{"text":{"type":"number"},"image":{"type":"number"},"video":{"type":"number"},"voice":{"type":"number"}}},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string","example":"pro"},"displayName":{"type":"string"},"priceLabel":{"type":"string"},"monthlyCredits":{"type":"number","nullable":true,"description":"null when the tier has unlimited credits"},"affords":{"type":"object","properties":{"text":{"type":"number","nullable":true},"image":{"type":"number","nullable":true},"video":{"type":"number","nullable":true},"voice":{"type":"number","nullable":true}}},"headroom":{"type":"string"},"upsell":{"type":"object","nullable":true,"properties":{"nextTier":{"type":"string"},"nextDisplayName":{"type":"string"},"creditMultiplier":{"type":"number"},"hint":{"type":"string"}}}}}}}}}}}}},"400":{"description":"Invalid cost override (must be positive finite number)."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/accounts":{"get":{"tags":["v1 / Account"],"summary":"List connected social accounts (v1)","operationId":"v1ListAccounts","description":"The social accounts connected for ONE brand (company) of the key owner — never every brand at once. Accounts shared into the brand from another brand are labelled with `shared` and `sharedFrom`.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands, or `personal`. Omitted: the brand active in the dashboard (Personal when none)."}],"responses":{"200":{"description":"Connected accounts.","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","example":"instagram"},"handle":{"type":"string"},"connectedAt":{"type":"integer","description":"Epoch ms."},"brandId":{"type":"string","description":"The brand the account belongs to, or `personal`."},"brandName":{"type":"string","nullable":true},"shared":{"type":"boolean","description":"Present (true) when shared from another brand; posts go out through the owner's connection."},"sharedFrom":{"type":"object","properties":{"brandId":{"type":"string"},"brandName":{"type":"string","nullable":true}}}}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"400":{"description":"Unknown brandId, or a brand the key owner is not a member of.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/content":{"get":{"tags":["v1 / Content"],"summary":"List content items (v1)","operationId":"v1ListContent","description":"Lists the key owner's most recent content (up to the newest 100 items), filtered and paged in memory. For the full library, brand scoping and live post status use GET /api/v2/content.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}},{"name":"type","in":"query","required":false,"schema":{"type":"string","example":"image"},"description":"Content type (e.g. `image`, `video`, `audio`, `text`)."},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only items created after this ISO time."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`nextCursor` from the previous page."}],"responses":{"200":{"description":"A page of content items.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"text":{"type":"string"},"imageUrl":{"type":"string","nullable":true},"audioUrl":{"type":"string","nullable":true},"videoUrl":{"type":"string","nullable":true},"contentType":{"type":"string","nullable":true},"platforms":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"aiModel":{"type":"string","nullable":true},"prompt":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"nextCursor":{"type":"string","nullable":true},"total":{"type":"integer","description":"Items matching the filters (within the newest 100)."}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/credits/balance":{"get":{"tags":["v1 / Account"],"summary":"Ember balance (v1)","operationId":"v1GetCreditBalance","description":"The Ember pool generations are charged to for the current period. Two pools: MONTHLY (the plan grant; unused grant carries over, capped at rolloverMonths × the monthly allowance; Free never carries) and PERMANENT (packs, grants and rewards; never expires). creditsRemaining = creditsCarriedOver + creditsAllowance + creditsEarned (legacy bonus) − this month's monthly usage + creditsPermanent. When the balance service is unreachable the figures are 0.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","responses":{"200":{"description":"Current balance.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"creditsUsed":{"type":"integer"},"creditsEarned":{"type":"integer"},"creditsRemaining":{"type":"integer"},"creditsAllowance":{"type":"integer"},"totalAllowance":{"type":"integer"},"periodsActive":{"type":"integer"},"rolloverEnabled":{"type":"boolean"},"creditsCarriedOver":{"type":"integer"},"creditsPermanent":{"type":"integer"},"rolloverMonths":{"type":"integer"},"rolloverCap":{"type":"integer"},"tier":{"type":"string"},"scope":{"type":"string","enum":["user","org"],"description":"`org` when the key owner is a member of an organisation plan: figures are the shared org pool."},"unlimited":{"type":"boolean"}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/credits/usage":{"get":{"tags":["v1 / Account"],"summary":"Generation counts and Embers used this month (v1)","operationId":"v1GetCreditUsage","description":"When the usage service is unreachable the figures are 0.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers (free, read-only)","responses":{"200":{"description":"Usage for the current month.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"textGenerations":{"type":"integer"},"imageGenerations":{"type":"integer"},"videoGenerations":{"type":"integer"},"voiceGenerations":{"type":"integer"},"creditsUsed":{"type":"integer"},"tier":{"type":"string"},"period":{"type":"string","example":"current_month"},"scope":{"type":"string","enum":["user","org"],"description":"`org` when the key owner is a member of an organisation plan: figures are the shared org pool."},"memberCount":{"type":"integer","description":"Members counted (1 for a personal plan)."}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/publish":{"post":{"tags":["v1 / Publishing"],"summary":"Publish a post now (v1)","operationId":"v1Publish","description":"Publishes immediately to the key owner's connected Personal accounts for the given platforms. For scheduling, brands, drafts and approval use POST /api/v2/publish. Per-platform status is `pending` on return; the outcome arrives by webhook.","security":[{"bearerAuth":[]}],"x-credit-cost":"0 Embers, except 100 Embers per X post that contains a link (X's API fee; refunded if the publish fails)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content","platforms"],"properties":{"content":{"type":"string","description":"The caption. Must not contain an unfilled `[you fill …]` placeholder."},"platforms":{"type":"array","minItems":1,"items":{"type":"string"},"example":["instagram","linkedin"]},"mediaUrls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Image / video URLs to attach."}}}}}},"responses":{"200":{"description":"Sent to the platforms.","content":{"application/json":{"schema":{"type":"object","properties":{"postId":{"type":"string"},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"status":{"type":"string","example":"pending"}}}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"400":{"description":"Invalid JSON; missing content or platforms; no social accounts connected, or none for the requested platforms; or an unresolvable Discord channel.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing, malformed (keys start with `flayr_sk_`), invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"403":{"description":"The key owner's plan does not include API access (Pro or higher).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"409":{"description":"A video's watermark is still rendering; retry after `retryAfterSeconds`. Nothing was posted.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"retryAfterSeconds":{"type":"integer"}}}}}},"422":{"description":"The caption still has an unfilled placeholder (`code: not_ready`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}},"429":{"description":"Per-minute rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Rate limit exceeded"},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer","example":0},"resetAt":{"type":"string","format":"date-time"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for the key owner's plan."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets."}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}},"503":{"description":"API key validation is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/v1/generate":{"post":{"tags":["v1 / Generation"],"summary":"Generate social copy or an image prompt (v1)","operationId":"v1Generate","description":"`type: text` returns short / long / hashtag copy for a topic; `type: image` returns an enhanced image-generation prompt (text only — use POST /api/v1/generate/image to render an image). The model is chosen by the key owner's plan.","security":[{"bearerAuth":[]}],"x-credit-cost":"1-5 Embers per request (text model weights)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","prompt"],"properties":{"type":{"type":"string","enum":["text","image"]},"prompt":{"type":"string"},"platform":{"type":"string","description":"Optimise text for this platform."}}}}}},"responses":{"200":{"description":"Generated.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"text","properties":{"type":{"type":"string","enum":["text"]},"content":{"type":"object","properties":{"short":{"type":"string"},"long":{"type":"string"},"hashtags":{"type":"string"}}},"model":{"type":"string"},"usage":{"type":"object","properties":{"promptTokens":{"type":"integer"},"completionTokens":{"type":"integer"},"totalTokens":{"type":"integer"}}}}},{"type":"object","title":"image","properties":{"type":{"type":"string","enum":["image"]},"description":{"type":"string"},"suggestedPrompt":{"type":"string"},"model":{"type":"string"},"usage":{"type":"object","properties":{"promptTokens":{"type":"integer"},"completionTokens":{"type":"integer"},"totalTokens":{"type":"integer"}}}}}]}}}},"400":{"description":"Invalid JSON, `type` not text/image, or missing prompt.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing Bearer token, or an invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}},"402":{"description":"Insufficient Embers (checked before generating).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"insufficient_credits"},"required":{"type":"integer"},"available":{"type":"integer"},"remaining":{"type":"integer"},"message":{"type":"string"}}}}}},"403":{"description":"The plan does not include the model (`tier_insufficient`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"tier_insufficient"},"requiredFor":{"type":"string"}}}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}}}}}}}},"/api/v2/rotations":{"get":{"operationId":"listRotations","tags":["Rotations"],"summary":"List brand rotations or generated weeks","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","schema":{"type":"string"}},{"name":"rotationId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Rotation definitions, or weeks with group id, accepted content ids and held reasons."}}},"post":{"operationId":"createRotation","tags":["Rotations"],"summary":"Create a brand hook rotation","security":[{"bearerAuth":[]}],"description":"Requires a brand owner/admin, scheduling entitlement and publish scope. No posts are booked until the weekly approval group is approved. Ads remain held.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["config"],"properties":{"brandId":{"type":"string"},"rotationId":{"type":"string"},"config":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"enabled":{"type":"boolean","default":false},"hooks":{"type":"array","items":{"type":"object","required":["id","line","theme"],"properties":{"id":{"type":"string"},"line":{"type":"string"},"theme":{"type":"string"}}}},"contents":{"type":"array","items":{"type":"object","required":["slug","contentId","body","aiLabel"],"properties":{"slug":{"type":"string"},"contentId":{"type":"string"},"body":{"type":"string"},"aiLabel":{"type":"boolean"},"disclosure":{"type":"string"},"hookIds":{"type":"array","items":{"type":"string"}},"ratioSiblings":{"type":"array","items":{"type":"object","required":["ratio","contentId","networks"],"properties":{"ratio":{"type":"string"},"contentId":{"type":"string"},"networks":{"type":"array","items":{"type":"string"}}}}}}}},"pairing":{"type":"string","enum":["per-content","full-cross"],"default":"full-cross"},"hookOrder":{"type":"array","items":{"type":"string"}},"contentOrder":{"type":"array","items":{"type":"string"}},"postsPerDay":{"type":"integer","minimum":1,"maximum":5,"default":2},"times":{"type":"array","items":{"type":"string"},"description":"Exactly postsPerDay distinct HH:mm local times. Default 08:30 and 20:30."},"networks":{"type":"array","items":{"type":"string"}},"timezone":{"type":"string","default":"America/Chicago"},"startsAt":{"type":"integer","description":"Epoch milliseconds, inclusive."},"weekStartsOn":{"type":"string","enum":["Mon"],"default":"Mon"},"generateDaysBefore":{"type":"integer","minimum":0,"maximum":6,"default":3},"maxPostsPerAccountPerDay":{"type":"integer","minimum":3,"maximum":5,"default":3},"youtubeDailyCap":{"type":"integer","minimum":0,"maximum":3,"default":3},"repeatWindowDays":{"type":"integer","minimum":7,"maximum":365,"default":7},"destinationUrl":{"type":"string","format":"uri","description":"HTTPS destination. Organic hook/content UTMs are appended."},"captionTemplate":{"type":"string","description":"Must include {hook}, {body}, {disclosure}, {url}. Template generation has no model charges."}},"required":["name","hooks","contents","networks","startsAt","destinationUrl"]}}}}}},"responses":{"201":{"description":"Created rotation id"},"422":{"description":"Invalid configuration or references"}}},"patch":{"operationId":"updateRotation","tags":["Rotations"],"summary":"Patch rotation settings for the next generated week","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rotationId","config"],"properties":{"brandId":{"type":"string"},"rotationId":{"type":"string"},"config":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"enabled":{"type":"boolean","default":false},"hooks":{"type":"array","items":{"type":"object","required":["id","line","theme"],"properties":{"id":{"type":"string"},"line":{"type":"string"},"theme":{"type":"string"}}}},"contents":{"type":"array","items":{"type":"object","required":["slug","contentId","body","aiLabel"],"properties":{"slug":{"type":"string"},"contentId":{"type":"string"},"body":{"type":"string"},"aiLabel":{"type":"boolean"},"disclosure":{"type":"string"},"hookIds":{"type":"array","items":{"type":"string"}},"ratioSiblings":{"type":"array","items":{"type":"object","required":["ratio","contentId","networks"],"properties":{"ratio":{"type":"string"},"contentId":{"type":"string"},"networks":{"type":"array","items":{"type":"string"}}}}}}}},"pairing":{"type":"string","enum":["per-content","full-cross"],"default":"full-cross"},"hookOrder":{"type":"array","items":{"type":"string"}},"contentOrder":{"type":"array","items":{"type":"string"}},"postsPerDay":{"type":"integer","minimum":1,"maximum":5,"default":2},"times":{"type":"array","items":{"type":"string"},"description":"Exactly postsPerDay distinct HH:mm local times. Default 08:30 and 20:30."},"networks":{"type":"array","items":{"type":"string"}},"timezone":{"type":"string","default":"America/Chicago"},"startsAt":{"type":"integer","description":"Epoch milliseconds, inclusive."},"weekStartsOn":{"type":"string","enum":["Mon"],"default":"Mon"},"generateDaysBefore":{"type":"integer","minimum":0,"maximum":6,"default":3},"maxPostsPerAccountPerDay":{"type":"integer","minimum":3,"maximum":5,"default":3},"youtubeDailyCap":{"type":"integer","minimum":0,"maximum":3,"default":3},"repeatWindowDays":{"type":"integer","minimum":7,"maximum":365,"default":7},"destinationUrl":{"type":"string","format":"uri","description":"HTTPS destination. Organic hook/content UTMs are appended."},"captionTemplate":{"type":"string","description":"Must include {hook}, {body}, {disclosure}, {url}. Template generation has no model charges."}}}}}}}},"responses":{"200":{"description":"Updated rotation id"},"422":{"description":"Invalid configuration or references"}}}},"/api/v2/music/tracks":{"get":{"operationId":"listMusicTracks","tags":["Music"],"security":[{"bearerAuth":[]}],"summary":"List music tracks in a brand library","description":"Requires read scope. Returns active tracks with audio URLs, license/attribution, mood/tags, and ad-use guidance. The library holds at most 200 tracks; no pagination.","parameters":[{"name":"brandId","in":"query","schema":{"type":"string","description":"Brand id or personal. Omit to use the key’s bound brand, otherwise the owner’s active brand."}},{"name":"includeArchived","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Music library.","content":{"application/json":{"schema":{"type":"object","properties":{"tracks":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid query."},"401":{"description":"Invalid or missing API key."},"403":{"description":"Insufficient scope or key bound to another brand."},"404":{"description":"Unknown or inaccessible brand."},"429":{"description":"Rate or quota limit."}}},"post":{"operationId":"createMusicTracks","tags":["Music"],"security":[{"bearerAuth":[]}],"summary":"Register one or more uploaded music tracks","description":"Requires write scope. First get a separate /api/v2/media/upload-url for each file and POST audio bytes with Content-Type to it. Then register 1–50 returned storageIds here in one transaction. All tracks are saved or none are; IDs are returned in input order. Does not generate music or charge Embers. Existing storage limits apply. On an uncertain response, list tracks and compare externalId before retrying; duplicates reject the entire batch.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["tracks"],"properties":{"brandId":{"type":"string","description":"Brand id or personal. Omit to use the key’s bound brand, otherwise the owner’s active brand."},"tracks":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["storageId","title","artist","source","sourceUrl","licenseCode","attributionRequired"],"properties":{"storageId":{"type":"string","description":"From POSTing audio bytes to a /api/v2/media/upload-url URL. Audio only, at most 50 MiB per file."},"title":{"type":"string","maxLength":200},"artist":{"type":"string","maxLength":200},"source":{"type":"string","maxLength":80,"description":"For example suno, commissioned, own, or a library name."},"sourceUrl":{"type":"string","format":"uri","description":"HTTP(S) credit link to the track or its library."},"licenseCode":{"type":"string","enum":["cc0","cc-by","suno-paid","suno-free","elevenlabs-paid","commissioned","own","youtube-audio-library","other"]},"licenseText":{"type":"string","maxLength":2000},"attributionRequired":{"type":"boolean"},"attributionLine":{"type":"string","maxLength":300,"description":"Required when attributionRequired is true."},"durationSeconds":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":3600},"mood":{"type":"string","maxLength":80},"tags":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":40}},"madeOn":{"type":"string","format":"date","description":"Generation date (YYYY-MM-DD); records when the Suno/ElevenLabs plan rights applied."},"externalId":{"type":"string","maxLength":200,"description":"Stable manifest/source id. Duplicates within this brand and origin are rejected, including archived tracks."},"adRightsConfirmed":{"type":"boolean","description":"For commissioned tracks: the agreement covers advertising."}}}}}}}}},"responses":{"201":{"description":"Registered tracks, in input order.","content":{"application/json":{"schema":{"type":"object","properties":{"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}}}}},"400":{"description":"Invalid body or batch size."},"401":{"description":"Invalid or missing API key."},"403":{"description":"Insufficient scope or key bound to another brand."},"404":{"description":"Unknown or inaccessible brand."},"422":{"description":"Invalid metadata, unavailable upload, non-audio/oversized file, duplicate externalId, read-only brand membership, or library limit. No tracks saved."},"429":{"description":"Rate or quota limit."}}}},"/api/v2/music/library":{"get":{"operationId":"listMusicLibrary","tags":["Music"],"security":[{"bearerAuth":[]}],"summary":"List flayr library music (live tracks)","description":"FFE-1679. Requires read scope. Returns live flayr library tracks with mood, uses, energy, length, a thumbnail waveform and the licence line. Licensed for use on flayr only: no audio URL is returned.","responses":{"200":{"description":"Live library tracks.","content":{"application/json":{"schema":{"type":"object","properties":{"tracks":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Invalid or missing API key."},"403":{"description":"Insufficient scope or key bound to another brand."},"404":{"description":"Unknown or inaccessible brand."},"429":{"description":"Rate or quota limit."}}}},"/api/v2/music/library/{id}/sections":{"get":{"operationId":"getMusicLibrarySections","tags":["Music"],"security":[{"bearerAuth":[]}],"summary":"Sections, beat grid and waveform of a library track","description":"FFE-1679. Requires read scope. Sections (intro, lift, drop, breakdown, ending), BPM, beat offset and peaks for choosing a clip that lands on a beat or section.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Track analysis.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key."},"403":{"description":"Insufficient scope or key bound to another brand."},"404":{"description":"No live library track with that id."},"429":{"description":"Rate or quota limit."}}}},"/api/v2/ping":{"get":{"tags":["API v2"],"summary":"API liveness and key check","description":"Public liveness: with no key it answers 200 `{ ok, authenticated: false, service, ts }`. With a key it returns the key metadata and `authenticated: true`; a bad key is 401. To test a key, check `authenticated`, not `ok`. `tier` is the key owner's current tier; `brandId`/`brandName` are null for an account-wide key.","security":[{},{"bearerAuth":[]}],"responses":{"200":{"description":"API up. `authenticated: true` with the key metadata when a valid key was sent; `authenticated: false` and no account fields when no key was sent.","content":{"application/json":{"schema":{"type":"object","required":["ok","authenticated","ts"],"properties":{"ok":{"type":"boolean"},"authenticated":{"type":"boolean","description":"True only when a valid key was sent. Check this to test a key."},"service":{"type":"string","description":"Present on the no-key answer: \"flayr-api\"."},"userId":{"type":"string","description":"Key owner (authenticated only)."},"tier":{"type":"string","description":"Key owner's current plan tier (authenticated only)."},"brandId":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"ts":{"type":"integer","description":"Server time (ms since epoch)."}}}}}},"401":{"description":"An Authorization header was sent but the key is invalid"},"429":{"description":"Per-IP rate limit (Retry-After)"}}}},"/api/v2/content":{"get":{"tags":["API v2"],"summary":"List content","description":"Returns content owned by the API key user, newest first. Each item carries `postState` and `posts` — where it was published or scheduled, per platform, with live URLs.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":20}},{"name":"includeArchived","in":"query","schema":{"type":"boolean","default":false}},{"name":"brandId","in":"query","schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. Omitted: the key's brand (brand-bound key) or the owner's active brand."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `nextCursor` of the previous page. Omitted: the first (newest) page."}],"responses":{"200":{"description":"Content list","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","nullable":true},"status":{"type":"string","description":"The content row's own status. It stays `draft` after publishing — see `postState` / `posts` for where it went out.","example":"draft"},"contentType":{"type":"string","nullable":true},"platforms":{"type":"array","items":{"type":"string"}},"imageUrl":{"type":"string","nullable":true},"videoUrl":{"type":"string","nullable":true},"images":{"type":"array","nullable":true,"items":{"type":"string"}},"createdAt":{"type":"integer","nullable":true,"description":"Epoch ms."},"updatedAt":{"type":"integer","nullable":true,"description":"Epoch ms."},"source":{"type":"string","nullable":true},"credits":{"type":"array","items":{"type":"object"}},"platformText":{"type":"object","additionalProperties":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"library":{"type":"object","description":"FFE-544: the Library item's own title and description (PATCH `library`). Not the YouTube title.","properties":{"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}}},"opus":{"type":"object","nullable":true,"properties":{"projectId":{"type":"string","nullable":true},"clipId":{"type":"string"}}},"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands, or \"personal\"."},"sourceLabel":{"type":"string","nullable":true},"lifecycleStatus":{"type":"string","nullable":true,"description":"idea · draft · ready · staged · scheduled · published · needs_attention · archived"},"textFormat":{"type":"string","nullable":true},"draftGroupId":{"type":"string","nullable":true},"seedSpans":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}}}},"verify":{"type":"array","items":{"type":"object","properties":{"claim":{"type":"string"},"status":{"type":"string"}}}},"videoWatermarked":{"type":"object","nullable":true,"properties":{"version":{"type":"integer"},"at":{"type":"integer"}}},"aiGenerated":{"type":"boolean","nullable":true,"description":"The post's explicit \"AI-generated\" label toggle (PATCH `aiGenerated`); null = automatic (on when flayr made the media)."},"durationMs":{"type":"integer","nullable":true,"description":"The attached video/audio length in ms, when it was measured; null otherwise."},"thumbnail":{"type":"object","nullable":true,"description":"The video's custom thumbnail / cover (set with PATCH thumbnailStorageId / thumbnailUrl / thumbnailFrameOffsetMs), sent at publish to YouTube (long-form), Facebook, LinkedIn, Instagram Reels, TikTok and Pinterest; X, Threads and Bluesky have no cover field. null when none is set (platforms use their own frame). An automatic poster stays in imageUrl and is never posted.","properties":{"url":{"type":"string","nullable":true,"description":"The cover image; null for a frame pick with no captured still."},"storageId":{"type":"string","nullable":true},"source":{"type":"string","enum":["upload","frame"]},"frameOffsetMs":{"type":"integer","nullable":true,"description":"Frame picks: ms from the start of the video (Instagram thumbOffset, TikTok cover timestamp)."}}},"postState":{"type":"string","nullable":true,"enum":["posted","scheduled",null],"description":"`posted` once any post made from this item went live, `scheduled` while one is booked, else null."},"posts":{"type":"array","items":{"type":"object","required":["id","postId","status","scheduledAt","publishedAt","createdAt","error","platforms"],"properties":{"id":{"type":"string","description":"Same as `convexPostId` from POST /api/v2/publish."},"postId":{"type":"string","nullable":true,"description":"Same as an entry of `postIds` from POST /api/v2/publish."},"status":{"type":"string","description":"pending · scheduled · publishing · published · partial (live on some platforms, failed on others) · failed · cancelled · review_held · held","example":"scheduled"},"scheduledAt":{"type":"integer","nullable":true,"description":"When it is scheduled to go out (epoch ms); null for publish-now posts."},"publishedAt":{"type":"integer","nullable":true,"description":"When it went live (epoch ms)."},"createdAt":{"type":"integer","description":"Epoch ms."},"error":{"type":"string","nullable":true,"description":"The failure reason reported for the post as a whole."},"platforms":{"type":"array","items":{"type":"object","required":["platform","status","url","platformPostId","publishedAt","error"],"properties":{"platform":{"type":"string","example":"youtube"},"status":{"type":"string","description":"pending · scheduled · publishing · published · failed · not_booked (requested but never booked at Zernio — no connected account in the brand, or missing from the Zernio post; see error) (a platform with no stored result carries the post's own status).","example":"published"},"url":{"type":"string","nullable":true,"description":"The live post on the platform, once known.","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},"platformPostId":{"type":"string","nullable":true,"description":"The platform's own id for the post (e.g. the YouTube video id)."},"publishedAt":{"type":"integer","nullable":true,"description":"Epoch ms."},"error":{"type":"string","nullable":true,"description":"Why this platform failed (or was dropped at publish), when it did."}}}}}},"description":"Posts made from this item, newest first (up to 20 on GET /api/v2/content/{id}, 5 per item on the list), with their status, scheduled time and per-platform status, live URL and failure reason. Read from Flayr's stored post records, which the platform webhooks and an hourly status sync keep current."},"transcript":{"type":"object","nullable":true,"description":"FFE-545: the item's saved transcript (POST /api/v2/content/{id}/transcribe), brand terms applied; null when it has none. Only on GET /api/v2/content/{id}, not the list.","properties":{"text":{"type":"string","description":"The full transcript, including any edit made in the Library."},"language":{"type":"string","nullable":true},"segments":{"type":"array","description":"Timed lines as transcribed (seconds from the start). Edits to `text` do not change them.","items":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"}}}},"wordsUrl":{"type":"string","nullable":true,"description":"Short-lived URL of the word timings JSON, `[{ w, s, e }]`."},"wordCount":{"type":"integer"},"durationSeconds":{"type":"number"},"edited":{"type":"boolean"},"updatedAt":{"type":"integer","description":"Epoch ms."}}}}}},"count":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` for the next page; null on the last page."}}}}}},"401":{"description":"Unauthorized"},"422":{"description":"A `cursor` this API did not issue"},"429":{"description":"Rate limited"}}},"post":{"tags":["API v2"],"summary":"Create content","description":"Create a draft content item from text plus an image/video URL, or a file uploaded via POST /api/v2/media/upload-url (imageStorageId / videoStorageId). Or copy an existing item into another brand with `copyFromContentId` (staff and the Agency plan; see that field). brandId files it into a specific brand from GET /api/v2/brands, or \"personal\"; omitted, it goes to the brand last active in the dashboard (required once the account is in more than one organization). Requires the write (or admin) scope. HELP CENTER (flayr staff only): `?help=` (or body `help` / `helpBinding`) binds the draft to a help center slot; when a post of it goes live on YouTube (POST /api/v2/publish with contentId), the video URL fills that slot automatically. Refused with 403, and no draft is created, for keys of non-staff accounts or content outside the internal brands set in /super-admin/help.","security":[{"bearerAuth":[]}],"parameters":[{"name":"help","in":"query","required":false,"schema":{"type":"string"},"description":"Staff only. Bind the draft to a help center slot: `` (its official tutorial, e.g. \"workflows\"), `:official|how-to|community`, a how-to slot key (e.g. \"flayr-04-workflows-light\") or `how-to-` (n = 1-13). Only one of ?help=, help and helpBinding."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"`text` is required, except with `copyFromContentId`.","properties":{"text":{"type":"string","minLength":1,"maxLength":10000},"copyFromContentId":{"type":"string","description":"COPY TO BRAND (staff and the Agency plan): the id of an existing item (GET /api/v2/content) to copy into `brandId` as a new draft. Images, video, slides, documents and thumbnails are copied into new storage objects, so deleting the source never breaks the copy. Combine only with `brandId` (required, a brand id — not \"personal\") and optionally `text` (replaces the caption; omitted = the source caption). Labels, mentions, campaign/experiment links and post history are not copied. Needs an account-wide key. Errors: 403 below the Agency plan or with a brand-bound key; 404 unknown item or brand; 409 the item changed mid-copy; 413 the brand's storage is full; 422 the item is already in that brand or its media is missing."},"platforms":{"type":"array","items":{"type":"string"}},"contentType":{"type":"string"},"imageUrl":{"type":"string"},"videoUrl":{"type":"string"},"imageStorageId":{"type":"string"},"videoStorageId":{"type":"string"},"brandId":{"type":"string","description":"An id from GET /api/v2/brands, or \"personal\"."},"sourceLabel":{"type":"string","maxLength":80},"youtube":{"type":"object","description":"Stored on the draft and used when it is published (POST /api/v2/publish with contentId). YouTube upload options, applied to YouTube targets only. madeForKids is always sent to YouTube (default false). A missing title is derived from the first sentence of the caption, cut to 100 characters at a word boundary. SCHEDULED UPLOADS: the video is uploaded ahead of scheduledAt. \"public\" is uploaded as private and released by YouTube at the scheduled time; \"unlisted\" is watchable by anyone with the link from upload time; \"private\" stays private.","properties":{"title":{"type":"string","minLength":1,"maxLength":100,"description":"No < or >."},"visibility":{"type":"string","enum":["public","private","unlisted"],"default":"public"},"madeForKids":{"type":"boolean","default":false},"categoryId":{"type":"string","pattern":"^\\d{1,3}$","description":"YouTube category id, e.g. \"28\" (Science & Technology). YouTube default: 22."},"playlistId":{"type":"string","description":"From GET /api/v2/youtube/playlists for the same brand."},"tags":{"type":"array","items":{"type":"string","maxLength":100},"description":"At most 500 characters combined."},"containsSyntheticMedia":{"type":"boolean","description":"AI-generated content disclosure."},"firstComment":{"type":"string","maxLength":10000,"description":"For scheduled videos, posted at the scheduled time."}}},"referralFooter":{"type":"boolean","description":"Caption watermark: appends \"Posted with flayr.social — try it: flayr.social/r//\" to each platform's text ( is your referral code — your custom one if you claimed it; names the platform: yt, x, li, ig, tt, fb, th, bs). (YouTube: description only, never the title; X: the shorter \"via flayr.social/r//x\" or nothing when it would not fit — your text is never cut). On by default. false removes it only on plans that can remove the Flayr watermark (Pro and up); omitted follows your watermark setting."},"credits":{"type":"array","maxItems":10,"description":"Creator credits for work this post uses. Added to the published caption above the flayr footer, one line each: model → \"Print your own: (model by )\"; other kinds → \"Credit: by <author> <url>\". Never added twice (a URL already in the caption is skipped); on X a shorter line (or no URL) is used, or the credits are left out, before the caption text is ever cut. YouTube: description only, never the title.","items":{"type":"object","required":["kind","url"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["model","music","footage","image","other"]},"url":{"type":"string","format":"uri","maxLength":2048,"description":"Absolute http(s) link to the credited work."},"author":{"type":"string","maxLength":200,"description":"Designer / artist / photographer."},"title":{"type":"string","maxLength":200},"site":{"type":"string","maxLength":200,"description":"Detected from the URL when omitted (e.g. MakerWorld, Printables, Thingiverse)."}}}},"labels":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"},"description":"Normalized \"key:value\" labels (keys and values are lower-cased, spaces become \"-\"). Linked keys: campaign:<media campaign id>, experiment:<experiment id> (+ variant:<name> or the experiment's compareKey), type:<post type> (short, long-form, carousel, image, text, reel, story, poem, timelapse…). Free keys work too: cut:opus, lane:tech, parent:pantheon-part-1, ab:<pair id> (an A/B pair). Labels are copied onto every post made from the draft, and compared in GET /api/v2/analytics/experiments."},"instanceLabels":{"type":"array","maxItems":20,"description":"Internal labels per platform/account instance. An array of {platform, accountId?, labels}; accountId is the Zernio connected account id. Omit accountId when unknown. instanceKey is derived as canonical platform + \":account:\" + URL-encoded account id, or \":pending\" when unknown (twitter canonicalizes to x). Replaces the instance set when editing; [] clears it. Never published.","items":{"type":"object","required":["platform","labels"],"additionalProperties":false,"properties":{"platform":{"type":"string"},"accountId":{"type":"string","maxLength":200},"labels":{"type":"array","maxItems":30,"items":{"type":"string"}}}}},"platformText":{"type":"object","description":"Per-platform captions: platform id → the caption that platform gets instead of `text`, e.g. { \"twitter\": \"short version\" }. Each must fit its platform: X 280 (a link counts 23, an emoji 2), Bluesky 300, Threads 500, Instagram 2200, LinkedIn 3000. Platforms without one get `text` when it fits, else an automatic short version: the first line, the credits in short form, as many hashtags as fit and the short flayr link (hashtags go first, then the credit link becomes \"Model by <author>\"; words are never cut). PATCH merges: a null (or \"\") value clears that platform, platformText: null clears all. At publish every platform is validated on its own caption: one failing platform no longer fails the others — the post publishes to the rest and reports the failures in platformErrors.","additionalProperties":{"type":"string","nullable":true,"maxLength":10000}},"help":{"type":"string","description":"Staff only. Bind the draft to a help center slot: `<feature>` (its official tutorial, e.g. \"workflows\"), `<feature>:official|how-to|community`, a how-to slot key (e.g. \"flayr-04-workflows-light\") or `how-to-<n>` (n = 1-13). Only one of ?help=, help and helpBinding."},"helpBinding":{"type":"object","additionalProperties":false,"required":["feature"],"description":"Staff only. The help center slot this draft's published YouTube video fills. Default: fills only an empty slot.","properties":{"feature":{"type":"string","description":"A help feature slug (see /help/features)."},"slot":{"type":"string","enum":["official","how-to","community"],"default":"official"},"howTo":{"oneOf":[{"type":"string"},{"type":"integer","minimum":1,"maximum":13}],"description":"The how-to slot (key or 1-13); required for slot \"how-to\" and must belong to `feature`."},"replace":{"type":"boolean","default":false,"description":"Replace a video already in the slot."}}}}}}}},"responses":{"201":{"description":"Content created (or copied)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"brandId":{"type":"string","nullable":true},"copiedFrom":{"type":"string","description":"With copyFromContentId: the source item id."},"helpBinding":{"type":"object","description":"Present when the draft was bound to a help slot.","properties":{"featureSlug":{"type":"string"},"slot":{"type":"string","enum":["official","how-to","community"]},"howToKey":{"type":"string","nullable":true},"status":{"type":"string","enum":["waiting","attached","slot_filled","failed"]}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope, a brand-bound key targeting another brand, a help binding the key owner may not make (staff only, internal brands), or (copyFromContentId) a plan below Agency or a brand-bound key"},"404":{"description":"Unknown brandId, or (copyFromContentId) an item the key owner cannot read"},"409":{"description":"copyFromContentId: the item changed while it was being copied"},"413":{"description":"copyFromContentId: the target brand's storage is full"},"422":{"description":"Validation error, or a storageId whose upload never landed"}}}},"/api/v2/brands/{id}/invites":{"post":{"tags":["API v2"],"summary":"Invite a client to view one brand","description":"Requires write scope and an organization owner/admin. Creates the same seven-day, verified-email invitation as Settings → Organization and sends its email. Acceptance grants viewer access to this brand only, never organization membership or access to sibling brands. Only viewer is supported. Brand-bound keys stay pinned to their brand. Uses the dashboard per-user invitation rate limit. A pending duplicate is refused. A 201 means the invitation exists; emailSent may still be false. Manage that pending invite in Settings → Organization instead of blindly retrying.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"One organization brand id from GET /api/v2/brands; not personal or all."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254},"role":{"type":"string","enum":["viewer"],"default":"viewer"}}},"example":{"email":"client@example.com","role":"viewer"}}}},"responses":{"201":{"description":"Invitation created; email delivery is reported separately","content":{"application/json":{"schema":{"type":"object","required":["brandId","role","success","emailSent"],"properties":{"brandId":{"type":"string"},"role":{"type":"string","enum":["viewer"]},"success":{"type":"boolean"},"emailSent":{"type":"boolean"},"reason":{"type":"string","description":"Email delivery failure reason, if available. The invitation still exists."}}}}}},"400":{"description":"Invalid JSON, archived brand, or a pending invitation already exists"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing write scope, key cannot reach this brand, or caller is not an org owner/admin"},"404":{"description":"Unknown or inaccessible brand"},"422":{"description":"Invalid email, unsupported role, unknown body field, or not an organization brand id"},"429":{"description":"Per-user invite limit, API rate limit or quota reached"}}}},"/api/v2/brands":{"get":{"tags":["API v2"],"summary":"List brands","description":"Brands the API key owner can file content into and publish through (use an id as brandId on POST /api/v2/content or POST /api/v2/publish). \"personal\" is always available. Each brand carries its website and a setup checklist: hasBrandKey (a live brand API key exists; the owner creates keys in Settings, never through the API), hasWebsite, hasCtaGoal (a tagged CTA goal) and adsConnected. setup is null when it could not be read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Brands","content":{"application/json":{"schema":{"type":"object","properties":{"brands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"website":{"type":"string","nullable":true},"setup":{"type":"object","nullable":true,"properties":{"hasBrandKey":{"type":"boolean"},"hasWebsite":{"type":"boolean"},"hasCtaGoal":{"type":"boolean"},"adsConnected":{"type":"boolean"}}}}}},"personal":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized"}}},"post":{"tags":["API v2"],"summary":"Create a brand","description":"Creates a brand in the API key owner's organization, exactly as \"New brand\" in the dashboard does: the owner must be an owner or admin of the organization, and the plan's brand limit applies (402 when it is reached; nothing is created). ACCOUNT-WIDE keys with the write (or admin) scope only: a key bound to one brand gets 403. The same key reaches the new brand straight away, so it can go on to PATCH /api/v2/brand/intelligence and POST /api/v2/content with the returned id. Optional profile, voice, colors and fonts are saved in the same call (the PATCH /api/v2/brand/intelligence shapes); if any of them is invalid, no brand is created. Each create is recorded in the organization's audit log against the API key. This creates a brand, never an API key.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"description":"Only these fields are accepted; an unknown field is a 422.","properties":{"name":{"type":"string","maxLength":200,"description":"The brand name. Must not match another active brand in the organization."},"website":{"type":"string","maxLength":200,"description":"The brand's website. Shortcut for profile.website."},"orgId":{"type":"string","description":"The organization to create in. Needed only when the key owner belongs to more than one: without it the call is a 422 (code ORG_REQUIRED) that lists them."},"logoStorageId":{"type":"string","description":"A storageId from POST /api/v2/media/upload-url (an image). It becomes the brand's primary logo."},"profile":{"type":"object","description":"Only the fields sent are changed. Unknown fields are a 422.","properties":{"companyName":{"type":"string","maxLength":200},"tagline":{"type":"string","maxLength":200},"mission":{"type":"string","maxLength":4000},"industry":{"type":"string","maxLength":200},"website":{"type":"string","maxLength":200},"competitors":{"type":"array","items":{"type":"string"}},"brandValues":{"type":"array","items":{"type":"string"}},"contentPillars":{"type":"array","items":{"type":"string"}},"targetDemographics":{"type":"object","properties":{"ageRanges":{"type":"array","items":{"type":"string"}},"gender":{"type":"string"},"location":{"type":"array","items":{"type":"string"}},"interests":{"type":"array","items":{"type":"string"}},"painPoints":{"type":"array","items":{"type":"string"}}}},"hashtagSets":{"type":"array","maxItems":20,"items":{"type":"object","required":["name","tags"],"properties":{"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"voice":{"type":"object","description":"The brand default voice. Created (as the default) when the brand has none.","properties":{"name":{"type":"string"},"tone":{"type":"string"},"style":{"type":"string"},"targetAudience":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"avoidWords":{"type":"array","items":{"type":"string"}},"sampleContent":{"type":"string"},"examplePosts":{"type":"array","items":{"type":"string"}},"exampleLinks":{"type":"array","items":{"type":"string"}},"guide":{"type":"string","maxLength":30000}}},"colors":{"type":"object","required":["primary"],"description":"REPLACES the brand palette, the same as saving Brand → Overview → Brand Colors: the stored list is primary, secondary, then palette (duplicates dropped); primary and secondary are its top two. 6-digit hex, `#` optional, stored lower case.","properties":{"primary":{"type":"string","pattern":"^#?[0-9a-fA-F]{6}$","example":"#ff6b00"},"secondary":{"type":"string","pattern":"^#?[0-9a-fA-F]{6}$","example":"#ff6b00"},"palette":{"type":"array","maxItems":16,"items":{"type":"string","pattern":"^#?[0-9a-fA-F]{6}$","example":"#ff6b00"},"description":"Further brand colors, in order."}}},"fonts":{"type":"object","description":"Font family names. A role left out keeps its stored font. At least one is required.","properties":{"heading":{"type":"string","maxLength":100,"example":"Inter"},"body":{"type":"string","maxLength":100,"example":"Inter"}}}}},"example":{"name":"Dragon Shop","website":"https://shop.example.com","voice":{"tone":"Warm and direct"},"colors":{"primary":"#ff6b00","secondary":"#1a1a1a"}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The new brand's id: use it as brandId on the other endpoints."},"name":{"type":"string"},"orgId":{"type":"string","description":"The organization the brand was created in."},"url":{"type":"string","description":"Where the owner sees the brand in the dashboard."},"website":{"type":"string","nullable":true},"logoAssetId":{"type":"string","nullable":true,"description":"The brand asset made from logoStorageId, or null."},"restored":{"type":"boolean","description":"true when an archived brand of the same name was brought back instead of a new one made."}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan's brand limit is reached (BRAND_LIMIT), or the organization's billing is on hold (ORG_BILLING_HELD). Nothing is created.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","description":"BRAND_LIMIT, ORG_BILLING_HELD, KEY_BOUND, KEY_REFUSED, FORBIDDEN, ORG_NOT_FOUND, NAME_TAKEN, ORG_REQUIRED, NO_ORG or INVALID."},"message":{"type":"string"},"organizations":{"type":"array","description":"Only with ORG_REQUIRED: the organizations the key owner belongs to. Send one id as orgId.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"403":{"description":"Missing write scope, a key bound to one brand (KEY_BOUND), or the key owner is not an owner or admin of the organization (FORBIDDEN)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","description":"BRAND_LIMIT, ORG_BILLING_HELD, KEY_BOUND, KEY_REFUSED, FORBIDDEN, ORG_NOT_FOUND, NAME_TAKEN, ORG_REQUIRED, NO_ORG or INVALID."},"message":{"type":"string"},"organizations":{"type":"array","description":"Only with ORG_REQUIRED: the organizations the key owner belongs to. Send one id as orgId.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"404":{"description":"orgId is not one of the key owner's organizations (ORG_NOT_FOUND)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","description":"BRAND_LIMIT, ORG_BILLING_HELD, KEY_BOUND, KEY_REFUSED, FORBIDDEN, ORG_NOT_FOUND, NAME_TAKEN, ORG_REQUIRED, NO_ORG or INVALID."},"message":{"type":"string"},"organizations":{"type":"array","description":"Only with ORG_REQUIRED: the organizations the key owner belongs to. Send one id as orgId.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"409":{"description":"An active brand with this name already exists (NAME_TAKEN)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","description":"BRAND_LIMIT, ORG_BILLING_HELD, KEY_BOUND, KEY_REFUSED, FORBIDDEN, ORG_NOT_FOUND, NAME_TAKEN, ORG_REQUIRED, NO_ORG or INVALID."},"message":{"type":"string"},"organizations":{"type":"array","description":"Only with ORG_REQUIRED: the organizations the key owner belongs to. Send one id as orgId.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"422":{"description":"Missing or over-long name, unknown field, bad profile / voice / color / font value, a logoStorageId that is not the caller's image upload, or no orgId for an owner in more than one organization (ORG_REQUIRED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","description":"BRAND_LIMIT, ORG_BILLING_HELD, KEY_BOUND, KEY_REFUSED, FORBIDDEN, ORG_NOT_FOUND, NAME_TAKEN, ORG_REQUIRED, NO_ORG or INVALID."},"message":{"type":"string"},"organizations":{"type":"array","description":"Only with ORG_REQUIRED: the organizations the key owner belongs to. Send one id as orgId.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"429":{"description":"Rate or quota limit"}}}},"/api/v2/youtube/playlists":{"get":{"tags":["API v2"],"summary":"List YouTube playlists","description":"Playlists of the YouTube channel(s) that POST /api/v2/publish with the same brandId uploads to. Use a playlist id as youtube.playlistId. A brand-bound key can only list its own brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."}],"responses":{"200":{"description":"Playlists per connected YouTube channel","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"accounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"name":{"type":"string"},"defaultPlaylistId":{"type":"string","nullable":true},"error":{"type":"string","description":"Set when this channel's playlists could not be read."},"playlists":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"privacy":{"type":"string","enum":["public","private","unlisted"]},"itemCount":{"type":"integer"}}}}}}}}}}}},"400":{"description":"The brand has no connected Zernio profile"},"401":{"description":"Unauthorized"},"403":{"description":"A brand-bound key asking for another brand"},"404":{"description":"Unknown brandId"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/pinterest/boards":{"get":{"tags":["API v2"],"summary":"List Pinterest boards","description":"Boards of the Pinterest account(s) that POST /api/v2/publish with the same brandId pins to. Use a board id as pinterest.boardId. A brand-bound key can only list its own brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."}],"responses":{"200":{"description":"Boards per connected Pinterest account","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"accounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"name":{"type":"string"},"error":{"type":"string","description":"Set when this account's boards could not be read."},"boards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"privacy":{"type":"string"}}}}}}}}}}}},"400":{"description":"The brand has no connected Zernio profile"},"401":{"description":"Unauthorized"},"403":{"description":"A brand-bound key asking for another brand"},"404":{"description":"Unknown brandId"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/media/upload-url":{"post":{"tags":["API v2"],"summary":"Get a file upload URL","description":"Returns a single-use URL. POST the file bytes to it with the file's Content-Type; the JSON response contains a storageId to pass as imageStorageId or videoStorageId on POST /api/v2/content. Requires the write (or admin) scope.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Upload URL","content":{"application/json":{"schema":{"type":"object","properties":{"uploadUrl":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/content/{id}":{"get":{"tags":["API v2"],"summary":"Get content by ID","description":"The content item plus its live post status: `postState` and `posts` (each post made from it, newest first, with status, scheduledAt and per-platform status / live URL / failure reason). The item's own `status` stays `draft` after publishing.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Content item","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","nullable":true},"status":{"type":"string","description":"The content row's own status. It stays `draft` after publishing — see `postState` / `posts` for where it went out.","example":"draft"},"contentType":{"type":"string","nullable":true},"platforms":{"type":"array","items":{"type":"string"}},"imageUrl":{"type":"string","nullable":true},"videoUrl":{"type":"string","nullable":true},"images":{"type":"array","nullable":true,"items":{"type":"string"}},"createdAt":{"type":"integer","nullable":true,"description":"Epoch ms."},"updatedAt":{"type":"integer","nullable":true,"description":"Epoch ms."},"source":{"type":"string","nullable":true},"credits":{"type":"array","items":{"type":"object"}},"platformText":{"type":"object","additionalProperties":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"library":{"type":"object","description":"FFE-544: the Library item's own title and description (PATCH `library`). Not the YouTube title.","properties":{"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}}},"opus":{"type":"object","nullable":true,"properties":{"projectId":{"type":"string","nullable":true},"clipId":{"type":"string"}}},"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands, or \"personal\"."},"sourceLabel":{"type":"string","nullable":true},"lifecycleStatus":{"type":"string","nullable":true,"description":"idea · draft · ready · staged · scheduled · published · needs_attention · archived"},"textFormat":{"type":"string","nullable":true},"draftGroupId":{"type":"string","nullable":true},"seedSpans":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}}}},"verify":{"type":"array","items":{"type":"object","properties":{"claim":{"type":"string"},"status":{"type":"string"}}}},"videoWatermarked":{"type":"object","nullable":true,"properties":{"version":{"type":"integer"},"at":{"type":"integer"}}},"aiGenerated":{"type":"boolean","nullable":true,"description":"The post's explicit \"AI-generated\" label toggle (PATCH `aiGenerated`); null = automatic (on when flayr made the media)."},"durationMs":{"type":"integer","nullable":true,"description":"The attached video/audio length in ms, when it was measured; null otherwise."},"thumbnail":{"type":"object","nullable":true,"description":"The video's custom thumbnail / cover (set with PATCH thumbnailStorageId / thumbnailUrl / thumbnailFrameOffsetMs), sent at publish to YouTube (long-form), Facebook, LinkedIn, Instagram Reels, TikTok and Pinterest; X, Threads and Bluesky have no cover field. null when none is set (platforms use their own frame). An automatic poster stays in imageUrl and is never posted.","properties":{"url":{"type":"string","nullable":true,"description":"The cover image; null for a frame pick with no captured still."},"storageId":{"type":"string","nullable":true},"source":{"type":"string","enum":["upload","frame"]},"frameOffsetMs":{"type":"integer","nullable":true,"description":"Frame picks: ms from the start of the video (Instagram thumbOffset, TikTok cover timestamp)."}}},"postState":{"type":"string","nullable":true,"enum":["posted","scheduled",null],"description":"`posted` once any post made from this item went live, `scheduled` while one is booked, else null."},"posts":{"type":"array","items":{"type":"object","required":["id","postId","status","scheduledAt","publishedAt","createdAt","error","platforms"],"properties":{"id":{"type":"string","description":"Same as `convexPostId` from POST /api/v2/publish."},"postId":{"type":"string","nullable":true,"description":"Same as an entry of `postIds` from POST /api/v2/publish."},"status":{"type":"string","description":"pending · scheduled · publishing · published · partial (live on some platforms, failed on others) · failed · cancelled · review_held · held","example":"scheduled"},"scheduledAt":{"type":"integer","nullable":true,"description":"When it is scheduled to go out (epoch ms); null for publish-now posts."},"publishedAt":{"type":"integer","nullable":true,"description":"When it went live (epoch ms)."},"createdAt":{"type":"integer","description":"Epoch ms."},"error":{"type":"string","nullable":true,"description":"The failure reason reported for the post as a whole."},"platforms":{"type":"array","items":{"type":"object","required":["platform","status","url","platformPostId","publishedAt","error"],"properties":{"platform":{"type":"string","example":"youtube"},"status":{"type":"string","description":"pending · scheduled · publishing · published · failed · not_booked (requested but never booked at Zernio — no connected account in the brand, or missing from the Zernio post; see error) (a platform with no stored result carries the post's own status).","example":"published"},"url":{"type":"string","nullable":true,"description":"The live post on the platform, once known.","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},"platformPostId":{"type":"string","nullable":true,"description":"The platform's own id for the post (e.g. the YouTube video id)."},"publishedAt":{"type":"integer","nullable":true,"description":"Epoch ms."},"error":{"type":"string","nullable":true,"description":"Why this platform failed (or was dropped at publish), when it did."}}}}}},"description":"Posts made from this item, newest first (up to 20 on GET /api/v2/content/{id}, 5 per item on the list), with their status, scheduled time and per-platform status, live URL and failure reason. Read from Flayr's stored post records, which the platform webhooks and an hourly status sync keep current."},"transcript":{"type":"object","nullable":true,"description":"FFE-545: the item's saved transcript (POST /api/v2/content/{id}/transcribe), brand terms applied; null when it has none. Only on GET /api/v2/content/{id}, not the list.","properties":{"text":{"type":"string","description":"The full transcript, including any edit made in the Library."},"language":{"type":"string","nullable":true},"segments":{"type":"array","description":"Timed lines as transcribed (seconds from the start). Edits to `text` do not change them.","items":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"}}}},"wordsUrl":{"type":"string","nullable":true,"description":"Short-lived URL of the word timings JSON, `[{ w, s, e }]`."},"wordCount":{"type":"integer"},"durationSeconds":{"type":"number"},"edited":{"type":"boolean"},"updatedAt":{"type":"integer","description":"Epoch ms."}}}}}}}},"404":{"description":"Not found or not owned"}}},"patch":{"tags":["API v2"],"summary":"Edit a draft","description":"Edit a content item in place — e.g. a draft waiting in a posting queue (queues read the draft when they book it, so edits made before booking are what gets published). Same access as GET; a brand-bound key only reaches its own brand. Requires the write (or admin) scope. Archived and already-published items are refused (409). Only the fields you pass change; `youtube` is merged field by field into the stored options; `credits` replaces the stored list ([] or null clears it). `labels`, `opus`, `videoWatermarked`, `library` (the Library title/description) and `aiGenerated` are metadata, not the draft: they may be set on booked and published items too (a body with only those skips the draft-only check). `aiGenerated` is the post's \"AI-generated\" label toggle: false for real footage, true to always label, null back to automatic (labelled when flayr made the media). Removing the `source:ai-generated` label alone does not turn it off. `videoWatermarked: { \"version\": 1 }` marks the item's OWN video as already carrying the \"Posted by flayr.social\" watermark, so publishing posts it as-is instead of burning in a second one; null clears it. A media change in the same body is applied first (and clears any earlier mark), so a swap + mark is one call. MEDIA: any of videoStorageId / videoUrl / imageStorageId / imageUrl / images replaces the draft's media as a set and keeps its id, so posting-queue items and schedules still point at it. A video (videoStorageId from POST /api/v2/media/upload-url, or videoUrl) may come with an image as its thumbnail; an image alone makes an image post; `images` (2-20 URLs) makes a carousel. contentType is set to video / image / carousel, and media the new set lacks (plus the old video's AI description/tags and AI slides) is cleared. The old upload is kept, not deleted. A media swap is refused (409) once a posting queue has booked the item (anything past \"queued\") or a scheduled/published post was made from it — those already carry the old media. THUMBNAIL: thumbnailStorageId (an image uploaded via POST /api/v2/media/upload-url) or thumbnailUrl sets the video's custom cover; thumbnailFrameOffsetMs picks a frame of the video instead (with an image, that image is the captured frame); thumbnailUrl: null clears it. At publish the cover goes to YouTube (long-form videos; Shorts ignore it), Facebook, LinkedIn, Instagram Reels (instagramThumbnail, or thumbOffset for a frame), TikTok (cover image — Zernio adds it as the first frame — or the frame timestamp) and Pinterest; X, Threads and Bluesky keep their own frame. Video drafts only; a media change in the same body is applied first. GET returns it as `thumbnail`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"text":{"type":"string","minLength":1,"maxLength":10000},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","description":"Merged into the stored YouTube options. YouTube upload options, applied to YouTube targets only. madeForKids is always sent to YouTube (default false). A missing title is derived from the first sentence of the caption, cut to 100 characters at a word boundary. SCHEDULED UPLOADS: the video is uploaded ahead of scheduledAt. \"public\" is uploaded as private and released by YouTube at the scheduled time; \"unlisted\" is watchable by anyone with the link from upload time; \"private\" stays private.","properties":{"title":{"type":"string","minLength":1,"maxLength":100,"description":"No < or >."},"visibility":{"type":"string","enum":["public","private","unlisted"],"default":"public"},"madeForKids":{"type":"boolean","default":false},"categoryId":{"type":"string","pattern":"^\\d{1,3}$","description":"YouTube category id, e.g. \"28\" (Science & Technology). YouTube default: 22."},"playlistId":{"type":"string","description":"From GET /api/v2/youtube/playlists for the same brand."},"tags":{"type":"array","items":{"type":"string","maxLength":100},"description":"At most 500 characters combined."},"containsSyntheticMedia":{"type":"boolean","description":"AI-generated content disclosure."},"firstComment":{"type":"string","maxLength":10000,"description":"For scheduled videos, posted at the scheduled time."}}},"title":{"type":"string","minLength":1,"maxLength":100,"description":"Shorthand for youtube.title (the video title). No < or >."},"credits":{"type":"array","maxItems":10,"description":"Creator credits for work this post uses. Added to the published caption above the flayr footer, one line each: model → \"Print your own: <url> (model by <author>)\"; other kinds → \"Credit: <title> by <author> <url>\". Never added twice (a URL already in the caption is skipped); on X a shorter line (or no URL) is used, or the credits are left out, before the caption text is ever cut. YouTube: description only, never the title.","items":{"type":"object","required":["kind","url"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["model","music","footage","image","other"]},"url":{"type":"string","format":"uri","maxLength":2048,"description":"Absolute http(s) link to the credited work."},"author":{"type":"string","maxLength":200,"description":"Designer / artist / photographer."},"title":{"type":"string","maxLength":200},"site":{"type":"string","maxLength":200,"description":"Detected from the URL when omitted (e.g. MakerWorld, Printables, Thingiverse)."}}},"nullable":true},"platformText":{"type":"object","description":"Per-platform captions: platform id → the caption that platform gets instead of `text`, e.g. { \"twitter\": \"short version\" }. Each must fit its platform: X 280 (a link counts 23, an emoji 2), Bluesky 300, Threads 500, Instagram 2200, LinkedIn 3000. Platforms without one get `text` when it fits, else an automatic short version: the first line, the credits in short form, as many hashtags as fit and the short flayr link (hashtags go first, then the credit link becomes \"Model by <author>\"; words are never cut). PATCH merges: a null (or \"\") value clears that platform, platformText: null clears all. At publish every platform is validated on its own caption: one failing platform no longer fails the others — the post publishes to the rest and reports the failures in platformErrors.","additionalProperties":{"type":"string","nullable":true,"maxLength":10000},"nullable":true},"labels":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"},"description":"Replaces the labels ([] or null clears). Allowed on published items too. Normalized \"key:value\" labels (keys and values are lower-cased, spaces become \"-\"). Linked keys: campaign:<media campaign id>, experiment:<experiment id> (+ variant:<name> or the experiment's compareKey), type:<post type> (short, long-form, carousel, image, text, reel, story, poem, timelapse…). Free keys work too: cut:opus, lane:tech, parent:pantheon-part-1, ab:<pair id> (an A/B pair). Labels are copied onto every post made from the draft, and compared in GET /api/v2/analytics/experiments.","nullable":true},"opus":{"type":"object","nullable":true,"additionalProperties":false,"required":["clipId"],"properties":{"projectId":{"type":"string","description":"Opus project id. Optional when clipId is the full \"{projectId}.{clipId}\" id."},"clipId":{"type":"string","description":"Opus clip id: the full \"{projectId}.{curationId}\" or the short curation id with projectId."}},"description":"Link this row to an Opus Clip clip (owner only; allowed on published rows) so an Opus project import skips it instead of creating a duplicate. null unlinks."},"library":{"type":"object","additionalProperties":false,"minProperties":1,"description":"The Library item's own title and description, searchable from the Library. null or \"\" clears one. Metadata: allowed on published items. Not the same as `title` (the YouTube video title).","properties":{"title":{"type":"string","nullable":true,"maxLength":120},"description":{"type":"string","nullable":true,"maxLength":2000}}},"aiGenerated":{"type":"boolean","nullable":true,"description":"The post's \"AI-generated\" label toggle: false = real footage (no AI label), true = always label, null = automatic (on when flayr made the media). Metadata: allowed on published items. Removing the `source:ai-generated` label alone does not turn it off."},"videoWatermarked":{"type":"object","nullable":true,"additionalProperties":false,"required":["version"],"properties":{"version":{"type":"integer","minimum":1,"maximum":1},"at":{"type":"integer","description":"When it was watermarked (epoch ms). Default: now."}},"description":"The item's own video already has the \"Posted by flayr.social\" watermark: publish it as-is. null clears."},"videoStorageId":{"type":"string","description":"storageId from uploading to POST /api/v2/media/upload-url's uploadUrl. Not with videoUrl. Another account's upload is refused (422)."},"videoUrl":{"type":"string","format":"uri","description":"http(s) URL of the new video. Not with videoStorageId."},"imageStorageId":{"type":"string","description":"Uploaded image storageId: the video's thumbnail, or on its own the post's single image. Not with imageUrl."},"imageUrl":{"type":"string","format":"uri","description":"http(s) image URL: the video's thumbnail, or on its own the post's single image. Not with imageStorageId."},"images":{"type":"array","minItems":2,"maxItems":20,"items":{"type":"string","format":"uri"},"description":"Carousel image URLs. Cannot be combined with the other media fields."},"thumbnailStorageId":{"type":"string","nullable":true,"description":"Custom video thumbnail: an image storageId from POST /api/v2/media/upload-url. Not with thumbnailUrl. null clears."},"thumbnailUrl":{"type":"string","format":"uri","nullable":true,"description":"Custom video thumbnail: an http(s) image URL. Not with thumbnailStorageId. null clears."},"thumbnailFrameOffsetMs":{"type":"integer","minimum":0,"maximum":86400000,"description":"Use this frame of the video (ms from the start) as the cover. Instagram and TikTok get the offset; YouTube/Facebook/LinkedIn need an image, so pass the captured frame as thumbnailStorageId / thumbnailUrl too."}}}}}},"responses":{"200":{"description":"The updated content item (same shape as GET, including credits and the new media / contentType)"},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope, or an org viewer editing another member's item"},"404":{"description":"Not found or not visible to this key"},"409":{"description":"Archived or already published; for a media swap, also when a posting queue already booked it or a scheduled/published post was made from it"},"422":{"description":"Validation error, or an upload that is missing or belongs to another account"},"429":{"description":"Rate or quota limit"}}},"delete":{"tags":["API v2"],"summary":"Delete content","description":"Permanently deletes the content item. Posts already live on a platform stay. Requires the write (or admin) scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"403":{"description":"Missing write scope"},"404":{"description":"Not found"}}}},"/api/v2/publish":{"post":{"tags":["API v2"],"summary":"Publish or schedule a post","description":"Posts to connected social accounts now, or schedules it with scheduledAt. Agency+ tier and the publish (or admin) scope are required to book; a key with only the write scope may file posts for review from the Business+ tier — every request is held as `pending-review` with its slot and full options until a person approves it. Pass either `content` (plus optional imageUrl / videoUrl) or `contentId` — an existing item from POST /api/v2/content, whose text and video / images / image become the post (`content` then overrides its text). The post goes out through the TARGET BRAND's own connected accounts: the content item's brand when contentId is given, else `brandId` (\"personal\" or an id from GET /api/v2/brands), else the key's bound brand. Without any of those, an account-wide key keeps the legacy behaviour (the owner's personal accounts). A brand-bound key can only publish into its own brand. `platformText` gives each platform its own caption (merged into the content item's stored ones and saved on it when contentId is given). Unknown body fields are refused (422 { code: \"unknown_fields\", unknownFields }), never silently ignored. Platform rules are enforced up front (e.g. YouTube requires a video). Pass idempotencyKey so a retried request returns the original result instead of posting twice. requiresApproval: true posts nothing and files a pending-approval item into the target brand instead. A contentId that is already scheduled on one of the platforms is not booked again (409 already_booked) unless allowDuplicateBooking is true; with onBooked: \"move\" its one live booking on those accounts is moved to scheduledAt instead (200 { moved: true, id, previousScheduledAt, scheduledAt, readback }). A second booking of the same draft on the same account within the identical-post window is refused by the booking gate (422 draft_already_scheduled) even with allowDuplicateBooking. When the target brand's scheduled-post review is \"required\", nothing is sent either: the response is { status: \"pending-review\", reviewId, convexPostId, contentId } and a reviewer approves it (POST /api/v2/reviews/{id}). Credit rules (GET /api/v2/attribution-rules): when the post misses a credit the target brand's rules require and the brand's mode is \"push_down\", \"post now\" returns 422 { code: \"attribution_missing\", failures: [{ ruleId, ruleName, reason }] } and a scheduled post is held the same way as a required review, with `heldReason`. In the default \"flag\" mode it posts as usual and `warnings` names the missing credit. Post quality checks (dashboard: Brand → Post review → Post quality checks): a caption on media that is only a title or too short, no destination link other than flayr when the post names a project or is cut from a longer video, markdown the platform will not render, a draft labelled review:needed, and the same media booked on the same platform at about the same time from another draft. By default each is a warning — the post goes out and the 200 response lists them in `warnings` and `qualityIssues`. A check the brand set to \"block\" returns 422 { code: \"post_quality\", qualityIssues } and nothing is sent. Platform fit (admin-set platform media rules): the video is measured from its header and checked against each platform and placement — length (e.g. \"TikTok max 60 s, this is 1:42\"), shape (\"16:9 on a vertical feed\"), the smallest frame, and loudness when known. Each problem is a line in `warnings`; with strictMedia: true the request is refused instead: 422 { code: \"media_fit\", mediaFit: [{ platform, label, check, severity, message, cutTargetSec? }], cuts: [{ platform, label, targetSec }] } and nothing is sent. A flayr credit line that does not fit the caption (X, Bluesky) is posted as a thread reply / first comment and named in `warnings`. X link posts: X charges per post that contains a link, so each X post (or thread item) with a link costs Embers (100 by default; admin-set) from the target brand's pool, charged before sending and refunded if the send fails. Short on Embers → 402 { code: \"x_link_post_insufficient_embers\", required, remaining, posts }; on a plan capped at its monthly X link posts → 402 { code: \"x_link_post_cap\" }. Nothing is sent in either case. flayr's own attribution link is never charged and is only added to an X post that already has a link.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platforms"],"properties":{"content":{"type":"string","minLength":1,"maxLength":10000,"description":"Post text. Required unless contentId is given."},"contentId":{"type":"string","description":"An existing content item id (GET /api/v2/content/{id} access rules). Cannot be combined with imageUrl / videoUrl."},"platforms":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","enum":["instagram","tiktok","youtube","youtube_shorts","linkedin","pinterest","twitter","facebook","threads","bluesky","snapchat","googlebusiness","google_business","reddit","telegram","discord"]}},"imageUrl":{"type":"string"},"videoUrl":{"type":"string"},"platformText":{"type":"object","description":"Per-platform captions for this post, the same shape, validation and limits as PATCH /api/v2/posts/{id}: { \"twitter\": \"…\" } gives X its own caption, null / \"\" clears one, null clears them all; an over-limit caption is a 422. With contentId they are merged into the item's stored captions and saved on it first (so a later edit, re-book or review uses the same ones); with `content` they apply on top of that text. Platforms without one get the text, auto-fit. Per-platform captions: platform id → the caption that platform gets instead of `text`, e.g. { \"twitter\": \"short version\" }. Each must fit its platform: X 280 (a link counts 23, an emoji 2), Bluesky 300, Threads 500, Instagram 2200, LinkedIn 3000. Platforms without one get `text` when it fits, else an automatic short version: the first line, the credits in short form, as many hashtags as fit and the short flayr link (hashtags go first, then the credit link becomes \"Model by <author>\"; words are never cut). PATCH merges: a null (or \"\") value clears that platform, platformText: null clears all. At publish every platform is validated on its own caption: one failing platform no longer fails the others — the post publishes to the rest and reports the failures in platformErrors.","additionalProperties":{"type":"string","nullable":true,"maxLength":10000},"nullable":true},"brandId":{"type":"string","description":"An id from GET /api/v2/brands, or \"personal\". With contentId it must match the item's brand."},"scheduledAt":{"type":"string","format":"date-time","description":"Must be in the future. Omitted → publish now."},"mediaCampaignId":{"type":"string","description":"Link to a media campaign; with a brand target it must belong to that brand."},"requiresApproval":{"type":"boolean","default":false},"aiGenerated":{"type":"boolean","description":"Label the post as AI-generated / synthetic media: YouTube containsSyntheticMedia, Instagram isAiGenerated, TikTok videoMadeWithAi, X madeWithAi, and the disclosure line (default \"#AIgenerated\") on platforms with no label field. Omitted → the content item's own setting, else on when its media was made with flayr AI (a character, a cloned voice, generated video or images). false on flayr-generated media posts without a label and adds a warning. A character post always carries the label."},"parody":{"type":"boolean","description":"FFE-1381: a parody post (labelled satire of a public figure). Needs the AI label too (`aiGenerated: true`, the item's own setting, or a character post); otherwise 422 `parody_refused`. Nude, sexual or intimate depictions of real people and content built to pass as a real statement or endorsement are refused (422 `parody_refused`, with `reasons` and `blocks`). A parody post carries the platform AI fields and the parody disclosure line (default \"#parody #AIgenerated\") on every target, and keeps the `mode:parody` label so a booked post stays parody (a bare `parody` label is accepted and stored as `mode:parody`). The rules are admin config."},"idempotencyKey":{"type":"string","maxLength":200,"description":"Unique per API key. A retry with the same key never posts twice."},"strictMedia":{"type":"boolean","default":false,"description":"Refuse (422 media_fit) when the video does not fit a booked platform (length, shape, smallest frame, loudness) instead of posting with `warnings`."},"allowDuplicateBooking":{"type":"boolean","default":false,"description":"A contentId that is already scheduled (a live booking still ahead) on one of these platforms is refused with 409 { code: \"already_booked\", bookedAt, bookedPlatforms }. Pass true only to book the same draft again on purpose (outside the identical-post window: inside it the gate refuses with draft_already_scheduled)."},"onBooked":{"type":"string","enum":["refuse","move"],"default":"refuse","description":"What a scheduled publish of an already-booked contentId does. \"move\" moves the draft's one live booking on these exact platforms to scheduledAt (the same move as PATCH /api/v2/posts/{id}), creates no new post, and returns the post read back. More than one booking, a booking you cannot view, or one on other platforms too: 409 booked_move_refused and nothing moves. Needs contentId and scheduledAt."},"instanceLabels":{"type":"array","maxItems":20,"description":"Internal labels per platform/account instance. An array of {platform, accountId?, labels}; accountId is the Zernio connected account id. Omit accountId when unknown. instanceKey is derived as canonical platform + \":account:\" + URL-encoded account id, or \":pending\" when unknown (twitter canonicalizes to x). Replaces the instance set when editing; [] clears it. Never published.","items":{"type":"object","required":["platform","labels"],"additionalProperties":false,"properties":{"platform":{"type":"string"},"accountId":{"type":"string","maxLength":200},"labels":{"type":"array","maxItems":30,"items":{"type":"string"}}}}},"labels":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"},"description":"Labels for this post on top of the draft's own (the draft wins for type/cut/variant). Normalized \"key:value\" labels (keys and values are lower-cased, spaces become \"-\"). Linked keys: campaign:<media campaign id>, experiment:<experiment id> (+ variant:<name> or the experiment's compareKey), type:<post type> (short, long-form, carousel, image, text, reel, story, poem, timelapse…). Free keys work too: cut:opus, lane:tech, parent:pantheon-part-1, ab:<pair id> (an A/B pair). Labels are copied onto every post made from the draft, and compared in GET /api/v2/analytics/experiments."},"youtube":{"type":"object","description":"Overrides the content item's stored YouTube options field by field. YouTube upload options, applied to YouTube targets only. madeForKids is always sent to YouTube (default false). A missing title is derived from the first sentence of the caption, cut to 100 characters at a word boundary. SCHEDULED UPLOADS: the video is uploaded ahead of scheduledAt. \"public\" is uploaded as private and released by YouTube at the scheduled time; \"unlisted\" is watchable by anyone with the link from upload time; \"private\" stays private.","properties":{"title":{"type":"string","minLength":1,"maxLength":100,"description":"No < or >."},"visibility":{"type":"string","enum":["public","private","unlisted"],"default":"public"},"madeForKids":{"type":"boolean","default":false},"categoryId":{"type":"string","pattern":"^\\d{1,3}$","description":"YouTube category id, e.g. \"28\" (Science & Technology). YouTube default: 22."},"playlistId":{"type":"string","description":"From GET /api/v2/youtube/playlists for the same brand."},"tags":{"type":"array","items":{"type":"string","maxLength":100},"description":"At most 500 characters combined."},"containsSyntheticMedia":{"type":"boolean","description":"AI-generated content disclosure."},"firstComment":{"type":"string","maxLength":10000,"description":"For scheduled videos, posted at the scheduled time."}}},"facebook":{"type":"object","additionalProperties":false,"description":"Facebook post type. \"reel\" posts a Reel (exactly one video, no images; anything else is a 422 with code content_type_invalid), \"story\" a Page Story, \"feed\" a regular post. Omitted → the content item's stored platformSpecificData.facebook.contentType (what the composer saved), else a regular post.","properties":{"contentType":{"type":"string","enum":["reel","story","feed"]}}},"instagram":{"type":"object","additionalProperties":false,"description":"Instagram post type, same rules: \"reel\" (exactly one video — a single video is posted as a Reel), \"story\", or \"feed\". Omitted → the content item's stored platformSpecificData.instagram.contentType. `trialReel` posts the Reel as an Instagram Trial Reel (shown to non-followers first): `graduation` \"manual\" (graduate it from the Instagram app) or \"auto\" (Instagram graduates it when it performs well); omitted → the admin default. Reels only: on a Story, images or a carousel it is ignored with a warning. A trial post is labelled `trial-reel:<graduation>`.","properties":{"contentType":{"type":"string","enum":["reel","story","feed"]},"trialReel":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"},"graduation":{"type":"string","enum":["manual","auto"]}}}}},"pinterest":{"type":"object","additionalProperties":false,"description":"FFE-428: Pinterest pin options for every Pinterest target. Overrides the content item's stored platformSpecificData.pinterest field by field. A board is required. boardId omitted → the brand's last-picked board for that Pinterest account, flagged in the response (defaultBoardApplied, defaultBoardName); with no default the publish is refused (422 pinterest_board_required). The board picked is remembered as the default. title omitted → the first line of the caption.","properties":{"boardId":{"type":"string","maxLength":200,"description":"From GET /api/v2/pinterest/boards for the same brand."},"title":{"type":"string","minLength":1,"maxLength":100},"link":{"type":"string","format":"uri","maxLength":2048,"description":"Destination link (http or https)."}}},"poll":{"type":"object","additionalProperties":false,"required":["options"],"description":"A native poll. Only on twitter (X), linkedin and discord, and with no media: any other platform or media is a 422 (code poll_invalid), never a plain post. X: 2-4 choices of at most 25 characters, 5 minutes to 7 days, and the post text is the question. LinkedIn: question (at most 140) required, 2-4 choices of at most 30 characters, 1, 3, 7 or 14 days. Discord: question (at most 300) required, 2-10 choices, whole hours up to 768. Cannot be combined with requiresApproval, or with a brand whose scheduled-post review is required (409 poll_not_holdable). Vote counts are not available through the API.","properties":{"question":{"type":"string","maxLength":300},"options":{"type":"array","minItems":2,"maxItems":10,"items":{"type":"string","minLength":1}},"durationMinutes":{"type":"integer","minimum":5,"default":1440}}},"referralFooter":{"type":"boolean","description":"Caption watermark: appends \"Posted with flayr.social — try it: flayr.social/r/<code>/<ch>\" to each platform's text (<code> is your referral code — your custom one if you claimed it; <ch> names the platform: yt, x, li, ig, tt, fb, th, bs). (YouTube: description only, never the title; X: the shorter \"via flayr.social/r/<code>/x\" or nothing when it would not fit — your text is never cut). On by default. false removes it only on plans that can remove the Flayr watermark (Pro and up); omitted follows your watermark setting. Beats the content item's stored value."},"reshare":{"type":"object","additionalProperties":false,"description":"Share/repost another post: a flayr post id (`postId`) or a pasted link (`url`). Per platform: linkedin a native reshare with your text on top (not with media or a poll); twitter a quote of your own X post, otherwise a retweet of it fired once this post publishes (no text); every other platform a link share — a new post carrying the original's link, because it has no repost API. X alone that can only retweet is a 422. Cannot be combined with requiresApproval.","properties":{"postId":{"type":"string"},"url":{"type":"string","example":"https://www.linkedin.com/feed/update/urn:li:share:7"}}},"followUpComments":{"type":"array","maxItems":20,"description":"Comments after publish, sent once each (Idempotency-Key) after the post is live on that platform and its tokens resolve: {{postUrl}}, {{postUrl:<platform>}}, {{parentPostUrl:<post or draft id>}}, {{youtubeUrl:<post or draft id>}}. TikTok: TikTok for Business accounts only (unverified); not on Pinterest.","items":{"type":"object","required":["platform","text"],"properties":{"platform":{"type":"string"},"text":{"type":"string"},"delayMinutes":{"type":"integer","minimum":0},"sendAt":{"type":"string","format":"date-time"}}}},"firstComment":{"type":"object","additionalProperties":false,"description":"Explicit first comments per platform, posted right after the post goes out. Always wins over the brand's auto first comment. Threads: posted as a reply (it counts toward Threads' 250 posts/24h). Facebook and Instagram: not on Stories. YouTube: use youtube.firstComment. Not supported on TikTok, X, Bluesky or Pinterest.","properties":{"linkedin":{"type":"string","maxLength":1250},"facebook":{"type":"string","maxLength":8000},"instagram":{"type":"string","maxLength":2200},"threads":{"type":"string","maxLength":500}}},"autoFirstComment":{"type":"boolean","default":true,"description":"When the target brand has \"Auto first comment\" on (dashboard: Brand → First comment), LinkedIn, Instagram, Facebook, Threads and YouTube targets that have no first comment of their own get the brand's comment, with a tracked link per platform. false posts this one without it. No effect when the brand has it off."},"memo":{"type":"object","description":"\"When it posts\" memo: the people-steps after the post goes live (reply to a comment, share to a personal account, pin a link, add a first comment flayr can't). Saved on the draft (else the post). When the post goes live, the brand's recipients (Brand → When a post goes live; default owners + admins) get ONE notice — in-app, email and push per their own settings — linking /publish/live/{convexPostId}: live links, the shared checklist, Copy buttons and a share link.","properties":{"notes":{"type":"string","maxLength":4000},"tasks":{"type":"array","maxItems":30,"items":{"oneOf":[{"type":"string","maxLength":500,"description":"The to-do, e.g. \"Share to personal LinkedIn\"."},{"type":"object","required":["text"],"properties":{"id":{"type":"string","description":"PUT only: keep an existing to-do (and its tick) by id."},"text":{"type":"string","maxLength":500},"copyText":{"type":"string","maxLength":5000,"description":"Text to paste (a reply, a first comment). The live page shows a Copy button."},"platform":{"type":"string","description":"The platform the step is for, e.g. \"youtube\"."},"url":{"type":"string","format":"uri","description":"Where to do it (http/https)."}}}]}}}},"onPublishTasks":{"type":"array","maxItems":30,"items":{"oneOf":[{"type":"string","maxLength":500,"description":"The to-do, e.g. \"Share to personal LinkedIn\"."},{"type":"object","required":["text"],"properties":{"id":{"type":"string","description":"PUT only: keep an existing to-do (and its tick) by id."},"text":{"type":"string","maxLength":500},"copyText":{"type":"string","maxLength":5000,"description":"Text to paste (a reply, a first comment). The live page shows a Copy button."},"platform":{"type":"string","description":"The platform the step is for, e.g. \"youtube\"."},"url":{"type":"string","format":"uri","description":"Where to do it (http/https)."}}}]},"description":"Shorthand for memo.tasks (appended after them). Response: `memoId`; a memo that could not be saved is a `warnings` entry, never a failed publish."}}}}}},"responses":{"200":{"description":"Posted or scheduled (or, with requiresApproval, filed for approval: { approvalId, contentId, status: \"pending-approval\" }). With requiresApproval on a video or voice whose Media QA check has not finished, the answer is 202 { approvalId: null, contentId, status: \"pending-media-qa\" }: the approval appears in Needs review when the check lands (poll GET /api/v2/content/{id}/qa).","content":{"application/json":{"schema":{"type":"object","properties":{"postIds":{"type":"array","items":{"type":"string"}},"scheduled":{"type":"boolean"},"platforms":{"type":"array","items":{"type":"string"},"description":"The platforms the post was actually booked on. A requested platform that failed validation or has no connected account in the brand is not listed; it is in platformErrors (a no-account drop starts \"Not booked:\" and is also named in warnings)."},"convexPostId":{"type":"string"},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Platforms whose caption was over the platform limit and was shortened to fit (the post still went to them). Absent when none were. Set a per-platform caption (platformText) to control the wording instead."},"brandId":{"type":"string","nullable":true,"description":"The brand the post went out through (\"personal\"), or null on the legacy path."},"contentId":{"type":"string"},"idempotent":{"type":"boolean","description":"true when this is the stored result of an earlier request with the same idempotencyKey."},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-fatal notices, e.g. a scheduled UNLISTED YouTube video is watchable by link before its scheduled time, or a post quality check (\"Post quality (<id>): …\")."},"qualityIssues":{"type":"array","description":"Post quality issues found (absent when none). level \"warn\" never stops a post; \"block\" only appears on a 422.","items":{"type":"object","properties":{"id":{"type":"string","enum":["thin_caption","missing_link","markdown","credit_overflow","needs_review","duplicate_booking","brand_terms"]},"level":{"type":"string","enum":["warn","block"]},"message":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}}}}}}}}}},"400":{"description":"No connected Zernio profile or no connected account for the requested platforms in the target brand. Destination refusals carry a stable `code`: `destination_required` — a platform has several connected accounts and the request names none (`accountIds`) and the brand has no default for it; `default_destination_unavailable` — the brand's default account for a platform is no longer connected; `destination_invalid` — `accountIds` is empty, repeats an id or names an account outside the brand; `destination_platform_missing` — `accountIds` leaves a requested platform without an account. Nothing is posted."},"401":{"description":"Unauthorized"},"402":{"description":"Agency+ tier required (Business+ for a write-only key filing for review; `requiresApproval` stays Agency+); or an X post with a link that the pool cannot pay for (`code: \"x_link_post_insufficient_embers\"`, with `required` / `remaining` / `posts`) or the plan's monthly X link posts are used (`code: \"x_link_post_cap\"`). Nothing is sent."},"403":{"description":"Missing publish scope, or a brand-bound key targeting another brand. Mention drafts: `code: \"mentions_feature_off\"` — the draft carries mentions but the mentions feature is off (remove the mentions or convert them to plain text); `code: \"account_forbidden\"` — a mention destination's publishing account is outside the authorized scope."},"404":{"description":"contentId not found (or outside the key's brand), or unknown brandId"},"409":{"description":"An earlier request with this idempotencyKey is still unaccounted for; `code: \"approval_required\"` means a required review is missing or pending (caller-forwarded `reviewApproved` / `approvedCaptionRevision` fields are ignored — approval is resolved server-side); `code: \"approval_stale\"` means the approved caption revision changed and must be reviewed again (the review is reopened); `code: \"snapshot_conflict\"` — the mention publication snapshot conflicts with an existing publication intent; or `code: \"watermark_pending\"` — the video's \"Posted by flayr.social\" copy is still rendering (usually a minute or two). Nothing was posted and no idempotency key was used: retry after `retryAfterSeconds`. `code: \"duplicate_content\"` — Zernio refused the post because this exact content is already scheduled, publishing or was posted to the account within the last 24 hours; the body carries Zernio's message as `error` plus `existingPostId`, `accountId` and `platform`. Nothing new was posted and the idempotency key is freed: change the content (or wait) to post it again. (`code: \"provider_conflict\"` is any other Zernio 409 refusal; nothing was posted.)"},"422":{"description":"Validation error: body (an over-limit platformText caption included), unknown body fields (code \"unknown_fields\", with `unknownFields`; `reviewApproved` / `approvedCaptionRevision` are accepted and ignored), past scheduledAt, platform media rules, brand / campaign mismatch; (code \"attribution_missing\") a missing credit in a push-down brand, with `failures`; (code \"mentions_content_override\") `content` may not replace the caption of a draft that carries mention bindings — edit the draft instead; (code \"post_quality\") a post quality check the brand set to \"block\" failed, with `qualityIssues`; or (code \"all_destinations_blocked\") every mention destination is blocked (unresolved mention, missing mapping, unrenderable identity, over-limit caption, or a resolver failure); or, with requiresApproval, (code \"media_qa_*\") a finished Media QA check refused the video, with `findings` (nothing is filed)."},"429":{"description":"Rate or quota limit"},"503":{"description":"`code: \"convex_unavailable\"` — a mention publication could not be authorized (feature, accounts, approval, evidence or snapshot store unreachable). Nothing was posted; retry."}}}},"/api/v2/generate/text":{"post":{"tags":["API v2"],"summary":"Generate text content","description":"AI-generated social post text. Credits: 5 Embers. Requires the write (or admin) scope. Pro+ plan. A brand-bound key may call it.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1},"platform":{"type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","threads","discord"]},"tone":{"type":"string"},"maxLength":{"type":"integer","minimum":50,"maximum":2000}}}}}},"responses":{"200":{"description":"Generated text","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"model":{"type":"string"},"platform":{"type":"string"}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing write scope"},"422":{"description":"Validation error"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/generate/image":{"post":{"tags":["API v2"],"summary":"Generate image","description":"AI-generated image from prompt. Returns CDN URL. Credits: 10 Embers. Requires the write (or admin) scope. Pro+ plan. A brand-bound key may call it.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"aspectRatio":{"type":"string","enum":["1:1","16:9","9:16","4:5"],"default":"1:1"},"platform":{"type":"string"},"style":{"type":"string","enum":["ai-generated","stock-overlay"],"default":"ai-generated","description":"ai-generated spends Embers on the image model. stock-overlay composites `overlayText` onto a free stock photo: brand-safety ranked, with 3-5 alternative photos returned as `candidates[]`."},"overlayText":{"type":"string","maxLength":500,"description":"Required for style \"stock-overlay\": the text burned onto the photo (an excerpt/pull-quote)."},"pick":{"type":"string","description":"For style \"stock-overlay\": the id of a candidate from a previous response's candidates[] to use instead of the brand-safe default."},"referenceImages":{"type":"array","minItems":1,"maxItems":3,"items":{"oneOf":[{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","pattern":"^https://","maxLength":2048,"description":"A public https PNG, JPEG, WebP or GIF image URL (no credentials; data: and http: are refused). Fetched server-side with private-address protection, at most 20 MB."}}},{"type":"object","required":["contentId"],"additionalProperties":false,"properties":{"contentId":{"type":"string","maxLength":200,"description":"An image content id from the Library (GET /api/v2/content) in the key's brand."}}}]},"description":"Up to 3 images the new image draws on (style, subject, composition). Google image models only (the default) — 422 \"referenceImages needs a Google image model\" otherwise. Same price as without references. Not accepted for style \"stock-overlay\"."}}},"examples":{"referenceImages":{"summary":"A keyframe in the style of two references","value":{"prompt":"A red dragon perched on a castle tower at dusk, cinematic","aspectRatio":"9:16","referenceImages":[{"url":"https://example.com/dragon-sketch.png"},{"contentId":"k57abc123def456"}]}}}}}},"responses":{"200":{"description":"Generated image","content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string"},"prompt":{"type":"string"},"aspectRatio":{"type":"string"},"referenceImages":{"type":"integer","description":"How many references were used (only when sent)."},"pickedCandidateId":{"type":"string","description":"stock-overlay only: the id of the photo composited."},"candidates":{"type":"array","maxItems":5,"description":"stock-overlay only: ranked alternative photos. Pass a candidate's id as `pick` on the next call to use it instead of the default.","items":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["pexels","pixabay","unsplash"]},"thumbnailUrl":{"type":"string"},"attributionUrl":{"type":"string"},"alt":{"type":"string","nullable":true},"author":{"type":"string"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}}},"description":"Brand-safety flags (text-in-photo, logo, person, low-relevance, no-alt) used to rank the photo."}}}}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing write scope"},"404":{"description":"A referenceImages contentId was not found in the key's brand"},"422":{"description":"Validation error (including a reference that is not https, cannot be fetched or is not an image)"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/generate/video":{"post":{"tags":["API v2"],"summary":"Generate video (async)","description":"Starts async video generation (Veo 3.1 Fast, text- or image-to-video). Returns 202 with job ID. Poll GET /api/v2/generate/status/{jobId} for completion. Credits: per second of video (the model's per-second Embers rate × duration; lower with audio off), checked before the job is queued. Requires the write (or admin) scope. Pro+ plan. Jobs made with a brand-bound key are tagged with that brand; only its keys can read them back.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"platform":{"type":"string"},"duration":{"type":"integer","enum":[3,4,6,8],"default":6,"description":"Clip length in seconds: 4, 6 or 8. 3 is deprecated and runs as 4 (Veo has no 3 s clip). Priced per second."},"aspectRatio":{"type":"string","enum":["16:9","9:16"],"default":"16:9"},"startImage":{"oneOf":[{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","pattern":"^https://","maxLength":2048,"description":"A public https PNG, JPEG or WebP image URL (no credentials; data: and http: are refused). Fetched server-side with private-address protection, at most 20 MB."}}},{"type":"object","required":["contentId"],"additionalProperties":false,"properties":{"contentId":{"type":"string","maxLength":200,"description":"An image content id from the Library (GET /api/v2/content) in the key's brand."}}}],"description":"Image-to-video: the clip starts from this image. A URL is stored in your media first. Same price as text-to-video. Style \"ai-generated\" only."},"audio":{"description":"Native audio & dialogue for models that generate their own soundtrack through the AI Gateway (Veo 3.x, Seedance 2.x, Kling 3.0, FLUX 3 Video, MiniMax H3, Grok Imagine 1.5). `true`/`false` or an object. Dialogue is spoken in the model's own voice, not a cloned one, and is trimmed to about 2.5 words per second of clip. Omitted = the model's default. Ignored by models without native audio. Veo 3.1 Fast with audio on costs 75 Embers per second instead of 50.","oneOf":[{"type":"boolean"},{"type":"object","properties":{"enabled":{"type":"boolean","description":"Native audio on/off. Off unless set to true (opt-in; dialogue and hints are ignored without it)."},"dialogue":{"type":"string","maxLength":600,"description":"Lines to be spoken (dialogue or narration)."},"voiceHint":{"type":"string","maxLength":200,"example":"woman in her 30s, warm and confident"},"soundHint":{"type":"string","maxLength":200,"example":"soft rain, distant city traffic"}}}]}}},"examples":{"startImage":{"summary":"Image-to-video from a keyframe, 8 s, vertical","value":{"prompt":"The dragon spreads its wings and takes off from the tower, camera follows","duration":8,"aspectRatio":"9:16","startImage":{"url":"https://example.com/dragon-keyframe.png"}}}}}}},"responses":{"202":{"description":"Job created","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["processing"]},"duration":{"type":"integer","description":"The clip length the job runs at (3 → 4)."},"startImage":{"type":"boolean","description":"true when a startImage was used."}}}}}},"402":{"description":"Pro+ plan required, or not enough Embers"},"403":{"description":"Missing write scope"},"404":{"description":"startImage contentId not found in the key's brand"},"413":{"description":"Storage full (startImage url could not be stored)"},"422":{"description":"Validation error (including a startImage that is not https, cannot be fetched or is not a PNG/JPEG/WebP image, or a video content)"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/generate/voice":{"get":{"tags":["API v2"],"summary":"List the voices you can speak with in a brand","description":"Your ready voice clones in the brand (never a teammate's) and the default one POST uses when `voiceId` is omitted. Free.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Brand id (GET /api/v2/brands), or `personal`. Default: a bound key's brand, else your active brand. A bound key may only name its own brand."}],"responses":{"200":{"description":"Voices","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"defaultVoiceId":{"type":"string","nullable":true},"voices":{"type":"array","items":{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"number","nullable":true,"description":"Epoch ms."}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Another brand than the key's"},"404":{"description":"Unknown brand"},"429":{"description":"Rate or quota limit"}}},"post":{"tags":["API v2"],"summary":"Generate a voice-over (speak a script)","description":"Speaks `text` in one of your voice clones (or a stock voice id) and waits for the audio. Costs Embers per 1,000 characters (cloned voices cost more than stock), checked before the job and charged to the brand's pool; a failed job is refunded.","security":[{"bearerAuth":[]}],"x-credit-cost":"flayr Voice: Embers per 1,000 characters of script (stock or cloned price)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"additionalProperties":false,"properties":{"text":{"type":"string","minLength":1,"maxLength":5000,"description":"The script."},"voiceId":{"type":"string","description":"A voiceId from GET /api/v2/generate/voice. Default: your newest ready clone in the brand."},"brandId":{"type":"string","description":"Brand id, or `personal`. Default: a bound key's brand, else your active brand."},"exaggeration":{"type":"number","description":"Expressiveness knob of the clone voice."},"cfgWeight":{"type":"number","description":"Pacing / adherence knob of the clone voice."}}}}}},"responses":{"200":{"description":"The audio","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string"},"audioUrl":{"type":"string","nullable":true},"text":{"type":"string"},"voiceId":{"type":"string"},"model":{"type":"string"},"brandId":{"type":"string","nullable":true},"credits":{"type":"object","properties":{"used":{"type":"number"},"remaining":{"type":"number"}}}}}}}},"400":{"description":"The body is not a JSON object"},"401":{"description":"Unauthorized"},"402":{"description":"Pro+ plan required, or not enough Embers"},"403":{"description":"Missing write scope, another brand, or a voiceId that is not yours (`voice_not_yours`)"},"404":{"description":"Unknown brand"},"422":{"description":"Validation error, or no ready clone in the brand to default to"},"429":{"description":"Rate or quota limit, or voice fair use (one job at a time; monthly cloned minutes)"},"502":{"description":"The voice job failed (refunded)"},"503":{"description":"Voice is not available on this environment"}}}},"/api/v2/brand/voices":{"get":{"tags":["API v2"],"summary":"Get default brand voice","description":"The brand's default writing voice (tone, style, keywords). For speaking voices see GET /api/v2/generate/voice.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Brand id (GET /api/v2/brands), or `personal`. Default: a bound key's brand, else your active brand. A bound key may only name its own brand."}],"responses":{"200":{"description":"Brand voice configuration"},"403":{"description":"Another brand than the key's"},"404":{"description":"No brand voice configured, or unknown brand"}}}},"/api/v2/analytics":{"get":{"tags":["API v2"],"summary":"Analytics overview","description":"Engagement analytics for the key's brand (a brand-bound key) or the owner's active brand, counting every member's posts in the brand by when they were published. `analytics.truncated` is true when the window holds more than 500 posts. Pro+ required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"}},{"name":"groupBy","in":"query","description":"A label key (e.g. `cut`, `variant`). Returns the per-label / per-experiment breakdown instead of brand totals: the same body as `GET /api/v2/analytics/experiments?key=<groupBy>` (which also takes `window`, `metric`, `brandId`, `format`, `include`).","schema":{"type":"string"}},{"name":"labelKey","in":"query","description":"FFE-1204: alias of `groupBy`. Use at most one of `groupBy`, `labelKey`, `experimentId` (two → 422).","schema":{"type":"string"}},{"name":"experimentId","in":"query","description":"FFE-1204: one experiment's per-variant results instead of brand totals: the same body as `GET /api/v2/experiments/{id}/results` (incl. % watched per arm; unreported watch data is `null`, never 0).","schema":{"type":"string"}}],"responses":{"200":{"description":"Analytics data (brand totals, or the label breakdown with `groupBy` / `labelKey`, or one experiment's results with `experimentId`)"},"402":{"description":"Pro+ required"}}}},"/api/v2/queues":{"get":{"tags":["API v2"],"summary":"List posting queues","description":"Posting (drip) queues of one brand. A queue publishes one item every cadenceHours at timeOfDay in its timezone, keeping `lookahead` items scheduled at the platform, and moves on past failures.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"responses":{"200":{"description":"Queues","content":{"application/json":{"schema":{"type":"object","properties":{"queues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"cadenceHours":{"type":"integer"},"timeOfDay":{"type":"string","example":"19:00"},"timezone":{"type":"string","example":"America/Chicago"},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","nullable":true},"lookahead":{"type":"integer"},"startsAt":{"type":"string","format":"date-time","nullable":true,"description":"Nothing posts before this instant; null = started right away."},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"publishing":{"type":"integer"},"scheduled":{"type":"integer"},"posted":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"}}},"nextSlotAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"A brand-bound key naming another brand"},"404":{"description":"Unknown brandId"}}},"post":{"tags":["API v2"],"summary":"Create a posting queue","description":"Agency+ tier and the publish (or admin) scope are required, as for POST /api/v2/publish. Defaults: daily (24h) at 19:00 America/Chicago, 2 scheduled ahead, YouTube public and not made for kids.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","platforms"],"properties":{"name":{"type":"string","maxLength":80},"platforms":{"type":"array","items":{"type":"string"},"minItems":1},"cadenceHours":{"type":"integer","default":24,"description":"1, 2, 3, 4, 6, 8, 12, or whole days (24, 48, …, 720)."},"timeOfDay":{"type":"string","default":"19:00","description":"24-hour \"HH:MM\" local time."},"timezone":{"type":"string","default":"America/Chicago","description":"IANA timezone. Slots keep their local time across DST."},"lookahead":{"type":"integer","minimum":1,"maximum":10,"default":2,"description":"How many upcoming items are scheduled at the platform at once."},"startsAt":{"type":"string","format":"date-time","example":"2026-09-28T19:00:00-05:00","description":"ISO 8601 with an offset (or Z). Nothing is booked before it; the first slot is the first timeOfDay (in the queue's timezone) at or after it, so a startsAt that is itself a slot is the first slot. A past date holds nothing back."},"youtube":{"type":"object","description":"Queue-wide YouTube defaults (a draft's own options win; titles are per item). YouTube upload options, applied to YouTube targets only. madeForKids is always sent to YouTube (default false). A missing title is derived from the first sentence of the caption, cut to 100 characters at a word boundary. SCHEDULED UPLOADS: the video is uploaded ahead of scheduledAt. \"public\" is uploaded as private and released by YouTube at the scheduled time; \"unlisted\" is watchable by anyone with the link from upload time; \"private\" stays private.","properties":{"title":{"type":"string","minLength":1,"maxLength":100,"description":"No < or >."},"visibility":{"type":"string","enum":["public","private","unlisted"],"default":"public"},"madeForKids":{"type":"boolean","default":false},"categoryId":{"type":"string","pattern":"^\\d{1,3}$","description":"YouTube category id, e.g. \"28\" (Science & Technology). YouTube default: 22."},"playlistId":{"type":"string","description":"From GET /api/v2/youtube/playlists for the same brand."},"tags":{"type":"array","items":{"type":"string","maxLength":100},"description":"At most 500 characters combined."},"containsSyntheticMedia":{"type":"boolean","description":"AI-generated content disclosure."},"firstComment":{"type":"string","maxLength":10000,"description":"For scheduled videos, posted at the scheduled time."}}},"brandId":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"cadenceHours":{"type":"integer"},"timeOfDay":{"type":"string","example":"19:00"},"timezone":{"type":"string","example":"America/Chicago"},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","nullable":true},"lookahead":{"type":"integer"},"startsAt":{"type":"string","format":"date-time","nullable":true,"description":"Nothing posts before this instant; null = started right away."},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"publishing":{"type":"integer"},"scheduled":{"type":"integer"},"posted":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"}}},"nextSlotAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["queued","publishing","scheduled","posted","failed","skipped"]},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"Booked slot, or the projected one when `projected` is true."},"projected":{"type":"boolean"},"youtubeTitle":{"type":"string","nullable":true},"pinnedAt":{"type":"string","format":"date-time","nullable":true},"reviewRequired":{"type":"boolean","description":"Explicit item requirement; the brand may additionally require review."},"platforms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"This item's own platforms (instead of the queue's); null = the queue's."},"partial":{"type":"boolean","description":"Scheduled / posted for some platforms only — see platformErrors. An item that reached no platform is `failed`."},"platformErrors":{"type":"array","description":"The platforms this item was not scheduled / posted to, and why (e.g. \"X (Twitter) max 280 characters (got 301)\").","items":{"type":"object","properties":{"platform":{"type":"string"},"message":{"type":"string"}}}},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Booked platforms whose caption was shortened to fit their limit (still posted). Absent when none were."},"error":{"type":"string"},"zernioPostId":{"type":"string"},"pushedDown":{"type":"string","nullable":true,"description":"Only in a brand whose attribution mode is push_down: the item was skipped at its turn because its draft lacks the credits the rules ask for (the next compliant item took the slot). It stays queued and books once it has them. null otherwise."},"attribution":{"type":"object","nullable":true,"description":"The brand's attribution rules (GET /api/v2/attribution-rules) checked against the draft, live. null = no rule applies.","properties":{"status":{"type":"string","enum":["ok","missing"]},"summary":{"type":"string","example":"Missing 3D model credit"},"failures":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"rule":{"type":"string"},"reason":{"type":"string"}}}}}}}}}}}]}}}},"402":{"description":"Agency+ required"},"403":{"description":"Missing publish scope, or a brand-bound key naming another brand"},"422":{"description":"Validation error (cadence, timezone, platforms, lookahead, plan without scheduling)"}}}},"/api/v2/queues/{id}":{"get":{"tags":["API v2"],"summary":"Get a posting queue","description":"The queue and its items in queue order, with booked or projected slots.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"responses":{"200":{"description":"Queue","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"cadenceHours":{"type":"integer"},"timeOfDay":{"type":"string","example":"19:00"},"timezone":{"type":"string","example":"America/Chicago"},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","nullable":true},"lookahead":{"type":"integer"},"startsAt":{"type":"string","format":"date-time","nullable":true,"description":"Nothing posts before this instant; null = started right away."},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"publishing":{"type":"integer"},"scheduled":{"type":"integer"},"posted":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"}}},"nextSlotAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["queued","publishing","scheduled","posted","failed","skipped"]},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"Booked slot, or the projected one when `projected` is true."},"projected":{"type":"boolean"},"youtubeTitle":{"type":"string","nullable":true},"pinnedAt":{"type":"string","format":"date-time","nullable":true},"reviewRequired":{"type":"boolean","description":"Explicit item requirement; the brand may additionally require review."},"platforms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"This item's own platforms (instead of the queue's); null = the queue's."},"partial":{"type":"boolean","description":"Scheduled / posted for some platforms only — see platformErrors. An item that reached no platform is `failed`."},"platformErrors":{"type":"array","description":"The platforms this item was not scheduled / posted to, and why (e.g. \"X (Twitter) max 280 characters (got 301)\").","items":{"type":"object","properties":{"platform":{"type":"string"},"message":{"type":"string"}}}},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Booked platforms whose caption was shortened to fit their limit (still posted). Absent when none were."},"error":{"type":"string"},"zernioPostId":{"type":"string"},"pushedDown":{"type":"string","nullable":true,"description":"Only in a brand whose attribution mode is push_down: the item was skipped at its turn because its draft lacks the credits the rules ask for (the next compliant item took the slot). It stays queued and books once it has them. null otherwise."},"attribution":{"type":"object","nullable":true,"description":"The brand's attribution rules (GET /api/v2/attribution-rules) checked against the draft, live. null = no rule applies.","properties":{"status":{"type":"string","enum":["ok","missing"]},"summary":{"type":"string","example":"Missing 3D model credit"},"failures":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"rule":{"type":"string"},"reason":{"type":"string"}}}}}}}}}}}]}}}},"404":{"description":"Not found in this workspace"}}},"patch":{"tags":["API v2"],"summary":"Update, pause or resume a posting queue","description":"Send any subset of the fields. `status: \"paused\"` stops new bookings (posts already scheduled at the platform stay scheduled); `\"active\"` resumes. Setting changes apply from the next booking on. Agency+ and the publish scope are required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"status":{"type":"string","enum":["active","paused"]},"name":{"type":"string","maxLength":80},"platforms":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Replaces the queue's platforms for items booked from now on. Already-booked items keep theirs; items with their own `platforms` keep using them."},"cadenceHours":{"type":"integer","description":"1, 2, 3, 4, 6, 8, 12, or whole days (24, 48, …, 720)."},"timeOfDay":{"type":"string","description":"24-hour \"HH:MM\" local time."},"lookahead":{"type":"integer","minimum":1,"maximum":10},"startsAt":{"type":"string","format":"date-time","example":"2026-09-28T19:00:00-05:00","description":"ISO 8601 with an offset (or Z). Nothing is booked before it; the first slot is the first timeOfDay (in the queue's timezone) at or after it, so a startsAt that is itself a slot is the first slot. A past date holds nothing back. null clears it.","nullable":true},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated queue","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"cadenceHours":{"type":"integer"},"timeOfDay":{"type":"string","example":"19:00"},"timezone":{"type":"string","example":"America/Chicago"},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","nullable":true},"lookahead":{"type":"integer"},"startsAt":{"type":"string","format":"date-time","nullable":true,"description":"Nothing posts before this instant; null = started right away."},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"publishing":{"type":"integer"},"scheduled":{"type":"integer"},"posted":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"}}},"nextSlotAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["queued","publishing","scheduled","posted","failed","skipped"]},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"Booked slot, or the projected one when `projected` is true."},"projected":{"type":"boolean"},"youtubeTitle":{"type":"string","nullable":true},"pinnedAt":{"type":"string","format":"date-time","nullable":true},"reviewRequired":{"type":"boolean","description":"Explicit item requirement; the brand may additionally require review."},"platforms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"This item's own platforms (instead of the queue's); null = the queue's."},"partial":{"type":"boolean","description":"Scheduled / posted for some platforms only — see platformErrors. An item that reached no platform is `failed`."},"platformErrors":{"type":"array","description":"The platforms this item was not scheduled / posted to, and why (e.g. \"X (Twitter) max 280 characters (got 301)\").","items":{"type":"object","properties":{"platform":{"type":"string"},"message":{"type":"string"}}}},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Booked platforms whose caption was shortened to fit their limit (still posted). Absent when none were."},"error":{"type":"string"},"zernioPostId":{"type":"string"},"pushedDown":{"type":"string","nullable":true,"description":"Only in a brand whose attribution mode is push_down: the item was skipped at its turn because its draft lacks the credits the rules ask for (the next compliant item took the slot). It stays queued and books once it has them. null otherwise."},"attribution":{"type":"object","nullable":true,"description":"The brand's attribution rules (GET /api/v2/attribution-rules) checked against the draft, live. null = no rule applies.","properties":{"status":{"type":"string","enum":["ok","missing"]},"summary":{"type":"string","example":"Missing 3D model credit"},"failures":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"rule":{"type":"string"},"reason":{"type":"string"}}}}}}}}}}}]}}}},"402":{"description":"Agency+ required"},"403":{"description":"Missing publish scope, or a brand-bound key naming another brand"},"404":{"description":"Not found in this workspace"},"422":{"description":"Validation error"}}},"delete":{"tags":["API v2"],"summary":"Delete a posting queue","description":"Deletes the queue; its drafts stay in the Library. A queue with posts booked at the platform (state `scheduled`) is refused with 409 unless `?unschedule=true`, which deletes each booked post at the platform and only then the queue. An item mid-booking (`publishing`) is always a 409 — try again shortly. If a platform delete fails the queue stays (502) and retrying is safe. Agency+ and the publish scope are required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."},{"name":"unschedule","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true: delete every booked post at the platform first (the dashboard's \"Unschedule\"), then delete. Without it a booked post is a 409 — nothing is ever left booked at the platform without its queue item."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"},"unscheduled":{"type":"integer","description":"Booked posts deleted at the platform."}}}}}},"402":{"description":"Agency+ required"},"403":{"description":"Missing publish scope, or a brand-bound key naming another brand"},"404":{"description":"Queue or item not found in this workspace"},"409":{"description":"Posts still booked (pass ?unschedule=true), or an item is mid-booking","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"booked":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string"},"slotAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"502":{"description":"A platform delete failed; the queue was left in place"}}}},"/api/v2/queues/{id}/items":{"post":{"tags":["API v2"],"summary":"Append drafts to a posting queue","description":"Adds drafts (GET /api/v2/content ids) to the end of the queue. Drafts of another brand, drafts already waiting in the queue, archived drafts and drafts without a video for a video platform are skipped and listed in `rejected`. Agency+ and the publish scope are required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentIds":{"type":"array","items":{"type":"string"},"maxItems":200},"items":{"type":"array","maxItems":200,"items":{"type":"object","required":["contentId"],"properties":{"labels":{"type":"array","maxItems":30,"items":{"type":"string"}},"instanceLabels":{"type":"array","maxItems":20,"description":"Internal labels per platform/account instance. An array of {platform, accountId?, labels}; accountId is the Zernio connected account id. Omit accountId when unknown. instanceKey is derived as canonical platform + \":account:\" + URL-encoded account id, or \":pending\" when unknown (twitter canonicalizes to x). Replaces the instance set when editing; [] clears it. Never published.","items":{"type":"object","required":["platform","labels"],"additionalProperties":false,"properties":{"platform":{"type":"string"},"accountId":{"type":"string","maxLength":200},"labels":{"type":"array","maxItems":30,"items":{"type":"string"}}}}},"contentId":{"type":"string"},"reviewRequired":{"type":"boolean","description":"Require explicit review even on optional/off brands. false never weakens brand policy."},"pinnedAt":{"type":"string","format":"date-time","description":"Exact slot with timezone offset; missed slots never publish late."},"youtubeTitle":{"type":"string","maxLength":100,"description":"The video's YouTube title. Omitted → the draft's stored title, else derived from its caption."},"platforms":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Post this item to these platforms instead of the queue's."}}}},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"Appended","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"integer"},"itemIds":{"type":"array","items":{"type":"string"}},"rejected":{"type":"array","items":{"type":"object","properties":{"contentId":{"type":"string"},"reason":{"type":"string"}}}},"queue":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"cadenceHours":{"type":"integer"},"timeOfDay":{"type":"string","example":"19:00"},"timezone":{"type":"string","example":"America/Chicago"},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","nullable":true},"lookahead":{"type":"integer"},"startsAt":{"type":"string","format":"date-time","nullable":true,"description":"Nothing posts before this instant; null = started right away."},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"publishing":{"type":"integer"},"scheduled":{"type":"integer"},"posted":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"}}},"nextSlotAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["queued","publishing","scheduled","posted","failed","skipped"]},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"Booked slot, or the projected one when `projected` is true."},"projected":{"type":"boolean"},"youtubeTitle":{"type":"string","nullable":true},"pinnedAt":{"type":"string","format":"date-time","nullable":true},"reviewRequired":{"type":"boolean","description":"Explicit item requirement; the brand may additionally require review."},"platforms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"This item's own platforms (instead of the queue's); null = the queue's."},"partial":{"type":"boolean","description":"Scheduled / posted for some platforms only — see platformErrors. An item that reached no platform is `failed`."},"platformErrors":{"type":"array","description":"The platforms this item was not scheduled / posted to, and why (e.g. \"X (Twitter) max 280 characters (got 301)\").","items":{"type":"object","properties":{"platform":{"type":"string"},"message":{"type":"string"}}}},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Booked platforms whose caption was shortened to fit their limit (still posted). Absent when none were."},"error":{"type":"string"},"zernioPostId":{"type":"string"},"pushedDown":{"type":"string","nullable":true,"description":"Only in a brand whose attribution mode is push_down: the item was skipped at its turn because its draft lacks the credits the rules ask for (the next compliant item took the slot). It stays queued and books once it has them. null otherwise."},"attribution":{"type":"object","nullable":true,"description":"The brand's attribution rules (GET /api/v2/attribution-rules) checked against the draft, live. null = no rule applies.","properties":{"status":{"type":"string","enum":["ok","missing"]},"summary":{"type":"string","example":"Missing 3D model credit"},"failures":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"rule":{"type":"string"},"reason":{"type":"string"}}}}}}}}}}}]}}}}}},"404":{"description":"Queue not found in this workspace"},"422":{"description":"Validation error"}}}},"/api/v2/queues/{id}/items/{itemId}":{"delete":{"tags":["API v2"],"summary":"Remove an item from a posting queue","description":"Removes a waiting item (queued, failed or skipped; posted rows too). A `scheduled` item is booked at the platform: 409 unless `?unschedule=true`, which deletes the platform post first and only then removes the item. A `publishing` item (mid-booking) is a 409 — try again shortly. The draft stays in the Library. Agency+ and the publish scope are required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."},{"name":"unschedule","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true: delete the booked post at the platform first (the dashboard's \"Unschedule\"), then delete. Without it a booked post is a 409 — nothing is ever left booked at the platform without its queue item."}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"},"unscheduled":{"type":"boolean"},"queue":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"cadenceHours":{"type":"integer"},"timeOfDay":{"type":"string","example":"19:00"},"timezone":{"type":"string","example":"America/Chicago"},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","nullable":true},"lookahead":{"type":"integer"},"startsAt":{"type":"string","format":"date-time","nullable":true,"description":"Nothing posts before this instant; null = started right away."},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"publishing":{"type":"integer"},"scheduled":{"type":"integer"},"posted":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"}}},"nextSlotAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["queued","publishing","scheduled","posted","failed","skipped"]},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"Booked slot, or the projected one when `projected` is true."},"projected":{"type":"boolean"},"youtubeTitle":{"type":"string","nullable":true},"pinnedAt":{"type":"string","format":"date-time","nullable":true},"reviewRequired":{"type":"boolean","description":"Explicit item requirement; the brand may additionally require review."},"platforms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"This item's own platforms (instead of the queue's); null = the queue's."},"partial":{"type":"boolean","description":"Scheduled / posted for some platforms only — see platformErrors. An item that reached no platform is `failed`."},"platformErrors":{"type":"array","description":"The platforms this item was not scheduled / posted to, and why (e.g. \"X (Twitter) max 280 characters (got 301)\").","items":{"type":"object","properties":{"platform":{"type":"string"},"message":{"type":"string"}}}},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Booked platforms whose caption was shortened to fit their limit (still posted). Absent when none were."},"error":{"type":"string"},"zernioPostId":{"type":"string"},"pushedDown":{"type":"string","nullable":true,"description":"Only in a brand whose attribution mode is push_down: the item was skipped at its turn because its draft lacks the credits the rules ask for (the next compliant item took the slot). It stays queued and books once it has them. null otherwise."},"attribution":{"type":"object","nullable":true,"description":"The brand's attribution rules (GET /api/v2/attribution-rules) checked against the draft, live. null = no rule applies.","properties":{"status":{"type":"string","enum":["ok","missing"]},"summary":{"type":"string","example":"Missing 3D model credit"},"failures":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"rule":{"type":"string"},"reason":{"type":"string"}}}}}}}}}}}]}}}}}},"402":{"description":"Agency+ required"},"403":{"description":"Missing publish scope, or a brand-bound key naming another brand"},"404":{"description":"Queue or item not found in this workspace"},"409":{"description":"Scheduled at the platform (pass ?unschedule=true), or mid-booking"},"502":{"description":"The platform delete failed; the item is still scheduled"}}},"patch":{"tags":["API v2"],"summary":"Skip, retry, unschedule, retitle or move a queue item","description":"Any subset, applied in order: `action`, then `youtubeTitle`, then `position`. skip — a queued item is passed over (state `skipped`); retry — a failed or skipped item goes back in line where it was; unschedule — a scheduled item's platform post is deleted, then the item goes back in line. The title can change while the item is queued or failed. `position` moves a queued item among the waiting items only. Agency+ and the publish scope are required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"action":{"type":"string","enum":["skip","retry","unschedule"]},"youtubeTitle":{"type":"string","maxLength":100,"nullable":true,"description":"null or \"\" → back to the draft's stored title."},"platforms":{"type":"array","minItems":1,"items":{"type":"string"},"nullable":true,"description":"This item's own platforms, used when it is booked; null → back to the queue's. Only before the item is booked (queued / failed / skipped)."},"position":{"type":"integer","minimum":0,"description":"0-based index among the waiting (queued) items."},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["queued","publishing","scheduled","posted","failed","skipped"]},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"Booked slot, or the projected one when `projected` is true."},"projected":{"type":"boolean"},"youtubeTitle":{"type":"string","nullable":true},"pinnedAt":{"type":"string","format":"date-time","nullable":true},"reviewRequired":{"type":"boolean","description":"Explicit item requirement; the brand may additionally require review."},"platforms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"This item's own platforms (instead of the queue's); null = the queue's."},"partial":{"type":"boolean","description":"Scheduled / posted for some platforms only — see platformErrors. An item that reached no platform is `failed`."},"platformErrors":{"type":"array","description":"The platforms this item was not scheduled / posted to, and why (e.g. \"X (Twitter) max 280 characters (got 301)\").","items":{"type":"object","properties":{"platform":{"type":"string"},"message":{"type":"string"}}}},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Booked platforms whose caption was shortened to fit their limit (still posted). Absent when none were."},"error":{"type":"string"},"zernioPostId":{"type":"string"},"pushedDown":{"type":"string","nullable":true,"description":"Only in a brand whose attribution mode is push_down: the item was skipped at its turn because its draft lacks the credits the rules ask for (the next compliant item took the slot). It stays queued and books once it has them. null otherwise."},"attribution":{"type":"object","nullable":true,"description":"The brand's attribution rules (GET /api/v2/attribution-rules) checked against the draft, live. null = no rule applies.","properties":{"status":{"type":"string","enum":["ok","missing"]},"summary":{"type":"string","example":"Missing 3D model credit"},"failures":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"rule":{"type":"string"},"reason":{"type":"string"}}}}}}}},"queue":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"cadenceHours":{"type":"integer"},"timeOfDay":{"type":"string","example":"19:00"},"timezone":{"type":"string","example":"America/Chicago"},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","nullable":true},"lookahead":{"type":"integer"},"startsAt":{"type":"string","format":"date-time","nullable":true,"description":"Nothing posts before this instant; null = started right away."},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"publishing":{"type":"integer"},"scheduled":{"type":"integer"},"posted":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"}}},"nextSlotAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["queued","publishing","scheduled","posted","failed","skipped"]},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"Booked slot, or the projected one when `projected` is true."},"projected":{"type":"boolean"},"youtubeTitle":{"type":"string","nullable":true},"pinnedAt":{"type":"string","format":"date-time","nullable":true},"reviewRequired":{"type":"boolean","description":"Explicit item requirement; the brand may additionally require review."},"platforms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"This item's own platforms (instead of the queue's); null = the queue's."},"partial":{"type":"boolean","description":"Scheduled / posted for some platforms only — see platformErrors. An item that reached no platform is `failed`."},"platformErrors":{"type":"array","description":"The platforms this item was not scheduled / posted to, and why (e.g. \"X (Twitter) max 280 characters (got 301)\").","items":{"type":"object","properties":{"platform":{"type":"string"},"message":{"type":"string"}}}},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Booked platforms whose caption was shortened to fit their limit (still posted). Absent when none were."},"error":{"type":"string"},"zernioPostId":{"type":"string"},"pushedDown":{"type":"string","nullable":true,"description":"Only in a brand whose attribution mode is push_down: the item was skipped at its turn because its draft lacks the credits the rules ask for (the next compliant item took the slot). It stays queued and books once it has them. null otherwise."},"attribution":{"type":"object","nullable":true,"description":"The brand's attribution rules (GET /api/v2/attribution-rules) checked against the draft, live. null = no rule applies.","properties":{"status":{"type":"string","enum":["ok","missing"]},"summary":{"type":"string","example":"Missing 3D model credit"},"failures":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"rule":{"type":"string"},"reason":{"type":"string"}}}}}}}}}}}]}}}}}},"402":{"description":"Agency+ required"},"403":{"description":"Missing publish scope, or a brand-bound key naming another brand"},"404":{"description":"Queue or item not found in this workspace"},"409":{"description":"The item is not in a state that allows this (e.g. moving an item that is not waiting, unscheduling one that is not scheduled)"},"422":{"description":"Validation error, or the change is not allowed for the item's state"},"502":{"description":"Unschedule: the platform delete failed; the item is still scheduled"}}}},"/api/v2/queues/{id}/items/reorder":{"post":{"tags":["API v2"],"summary":"Reorder the waiting items of a posting queue","description":"Send every waiting (queued) item id exactly once, in the new order. Booked, posted, failed and skipped items keep their places. Agency+ and the publish scope are required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["itemIds"],"properties":{"itemIds":{"type":"array","items":{"type":"string"}},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"Reordered queue","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"cadenceHours":{"type":"integer"},"timeOfDay":{"type":"string","example":"19:00"},"timezone":{"type":"string","example":"America/Chicago"},"platforms":{"type":"array","items":{"type":"string"}},"youtube":{"type":"object","nullable":true},"lookahead":{"type":"integer"},"startsAt":{"type":"string","format":"date-time","nullable":true,"description":"Nothing posts before this instant; null = started right away."},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"publishing":{"type":"integer"},"scheduled":{"type":"integer"},"posted":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"}}},"nextSlotAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["queued","publishing","scheduled","posted","failed","skipped"]},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"Booked slot, or the projected one when `projected` is true."},"projected":{"type":"boolean"},"youtubeTitle":{"type":"string","nullable":true},"pinnedAt":{"type":"string","format":"date-time","nullable":true},"reviewRequired":{"type":"boolean","description":"Explicit item requirement; the brand may additionally require review."},"platforms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"This item's own platforms (instead of the queue's); null = the queue's."},"partial":{"type":"boolean","description":"Scheduled / posted for some platforms only — see platformErrors. An item that reached no platform is `failed`."},"platformErrors":{"type":"array","description":"The platforms this item was not scheduled / posted to, and why (e.g. \"X (Twitter) max 280 characters (got 301)\").","items":{"type":"object","properties":{"platform":{"type":"string"},"message":{"type":"string"}}}},"truncatedPlatforms":{"type":"array","items":{"type":"string"},"description":"Booked platforms whose caption was shortened to fit their limit (still posted). Absent when none were."},"error":{"type":"string"},"zernioPostId":{"type":"string"},"pushedDown":{"type":"string","nullable":true,"description":"Only in a brand whose attribution mode is push_down: the item was skipped at its turn because its draft lacks the credits the rules ask for (the next compliant item took the slot). It stays queued and books once it has them. null otherwise."},"attribution":{"type":"object","nullable":true,"description":"The brand's attribution rules (GET /api/v2/attribution-rules) checked against the draft, live. null = no rule applies.","properties":{"status":{"type":"string","enum":["ok","missing"]},"summary":{"type":"string","example":"Missing 3D model credit"},"failures":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"rule":{"type":"string"},"reason":{"type":"string"}}}}}}}}}}}]}}}},"402":{"description":"Agency+ required"},"403":{"description":"Missing publish scope, or a brand-bound key naming another brand"},"404":{"description":"Queue or item not found in this workspace"},"409":{"description":"`itemIds` is not exactly the current waiting items","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"waitingItemIds":{"type":"array","items":{"type":"string"}},"notWaiting":{"type":"array","items":{"type":"string"}}}}}}},"422":{"description":"Validation error"}}}},"/api/v2/campaigns/builder/estimate":{"post":{"tags":["API v2"],"summary":"Estimate a campaign from a brief","description":"Plans the campaign arc for a brief (the slots and their times) and prices the drafts it would generate. Creates nothing and charges nothing. Needs `read`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","startDate","endDate"],"properties":{"brandId":{"type":"string","description":"Brand to act in. A brand-bound key acts in its own brand (another brandId is 403); an account-wide key defaults to the owner's active brand."},"name":{"type":"string","maxLength":120,"description":"Campaign name."},"startDate":{"oneOf":[{"type":"string","description":"ISO 8601 date or date-time"},{"type":"number","description":"Unix milliseconds"}]},"endDate":{"oneOf":[{"type":"string","description":"ISO 8601 date or date-time"},{"type":"number","description":"Unix milliseconds"}]},"timezone":{"type":"string","description":"IANA timezone, e.g. America/New_York. Default: the workspace's."},"goal":{"type":"string","maxLength":40,"examples":["engagement","sale","launch","holiday","custom"],"description":"Picks the arc phases and default platforms. A goal id from the campaign builder config: built in are \"engagement\", \"sale\", \"launch\", \"holiday\" (admins can add more without a deploy), or \"custom\" with customGoal. Default: \"custom\" when customGoal is set, else the configured default goal (\"engagement\"). Engagement needs no offer, price or deadline."},"customGoal":{"description":"Create your own goal (goal \"custom\"): the goal in the owner's words, used as the campaign goal in every caption prompt. A bare string is the text. Phases follow the closest built-in template (by the config's keywords) unless `template` picks one.","oneOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":1000,"description":"One sentence, e.g. \"Get more people to book a free consultation\"."},"successMeasures":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Success-measure ids from the config: comments, replies, saves, shares, link_clicks, messages, sign_ups, visits, sales."},"template":{"type":"string","enum":["engagement","sale","launch","holiday"],"description":"The built-in template to plan with. Default: the closest one to the text."}}}]},"source":{"type":"string","enum":["store","brand"],"description":"What the posts are built from. \"store\" (default): the featured products. \"brand\": no store needed — the brand kit and voice, the website, the Library and post themes, plus the optional interview. A brand campaign sends no products and needs no offer (set offer.noSale unless it is a deal); it works with any goal, including \"engagement\" and \"custom\"."},"interview":{"type":"object","description":"Brand campaigns only, every answer optional: what the business is promoting or talking about this month, anything coming up, and who the posts are for.","properties":{"promoting":{"type":"string","maxLength":1000,"description":"What are you promoting or talking about this month?"},"upcoming":{"type":"string","maxLength":1000,"description":"Anything coming up?"},"audience":{"type":"string","maxLength":1000,"description":"Who is it for?"}}},"offer":{"type":"object","description":"Required, with a headline, for a store campaign whose goal needs an offer (sale, launch, holiday). Optional for engagement and custom goals, and for a brand campaign (its headline falls back to the \"promoting\" answer, then a configured focus). Captions state when the offer ends only when it has endsAt or a discountPercent (a discount ends with the campaign). startsAt / endsAt are the offer's own days when it runs on only some of the campaign's days (Cyber Week: campaign Mon 11/23 – Tue 12/1, offer Fri 11/27 – Mon 11/30): the teaser and countdown are planned before startsAt, the last-chance post on the day of endsAt and the thank-you after it. Without them the offer days are the campaign's days.","properties":{"headline":{"type":"string","maxLength":200},"discountPercent":{"type":"number","exclusiveMinimum":0,"maximum":100},"code":{"type":"string","maxLength":64},"freeShipping":{"type":"boolean"},"terms":{"type":"string","maxLength":1000},"startsAt":{"oneOf":[{"type":"string","description":"ISO 8601 date or date-time"},{"type":"number","description":"Unix milliseconds"}],"description":"First instant of the offer. Use a date-time with an offset; a bare date is read as UTC midnight."},"endsAt":{"oneOf":[{"type":"string","description":"ISO 8601 date or date-time"},{"type":"number","description":"Unix milliseconds"}],"description":"Last instant of the offer; captions state it as the end. Use a date-time with an offset; a bare date is read as UTC midnight."},"noSale":{"type":"boolean","description":"The campaign is not a sale: captions state no discount, code, free shipping or end, even when those fields are set."}}},"products":{"type":"array","description":"Featured products (at most the configured product cap). Shopify: {source:\"shopify\", productGid}. Others: {source:\"manual\"|\"url\", title, price?, url?, imageUrl?, description?}.","items":{"type":"object","required":["source"],"properties":{"source":{"type":"string","enum":["shopify","manual","url"]},"productGid":{"type":"string","description":"gid://shopify/Product/… (source shopify)."},"title":{"type":"string","maxLength":200},"price":{"type":"number","minimum":0},"compareAtPrice":{"type":"number","minimum":0},"url":{"type":"string","maxLength":2000},"imageUrl":{"type":"string","maxLength":2000},"description":{"type":"string","maxLength":2000}}}},"platforms":{"type":"array","maxItems":10,"items":{"type":"string"},"description":"Platform ids (instagram, tiktok, …). Empty = the configured platforms for the goal."},"overrides":{"type":"object","properties":{"postingHour":{"type":"integer","minimum":0,"maximum":23},"requireReview":{"type":"boolean","description":"Hold booked posts for review before they go live."},"images":{"type":"string","enum":["product_photo","none"]},"phases":{"type":"object","description":"Overrides per arc phase.","properties":{"teaser":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"countdown":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"launch":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"product":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"mid_sale":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"last_chance":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"thank_you":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"warm_up":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"conversation":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"follow_up":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}}}}}}}}}}},"responses":{"200":{"description":"Plan and estimate","content":{"application/json":{"schema":{"type":"object","properties":{"slots":{"type":"array","items":{"type":"object","properties":{"phase":{"type":"string"},"role":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"scheduledAt":{"type":"string","format":"date-time"},"past":{"type":"boolean","description":"Already past: no draft is made for it."},"product":{"type":"object","nullable":true}}}},"estimate":{"type":"object","description":"Upper bound of the Embers generation charges. Failed calls are not charged.","properties":{"embers":{"type":"number"},"calls":{"type":"integer"},"unitEmbers":{"type":"number"},"upperBound":{"type":"boolean"},"lines":{"type":"array","items":{"type":"object","properties":{"slotIndex":{"type":"integer"},"phase":{"type":"string"},"feature":{"type":"string"},"calls":{"type":"integer"},"embers":{"type":"number"}}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brandId outside a brand-bound key"},"404":{"description":"Unknown brandId"},"422":{"description":"Bad brief"},"429":{"description":"Rate limit or monthly quota"}}}},"/api/v2/campaigns/builder":{"post":{"tags":["API v2"],"summary":"Create a campaign from a brief","description":"Creates a draft organic-social campaign and its brief in the brand, and returns the planned slots and the generation estimate. Charges nothing; generate drafts next. Needs `write`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","startDate","endDate"],"properties":{"brandId":{"type":"string","description":"Brand to act in. A brand-bound key acts in its own brand (another brandId is 403); an account-wide key defaults to the owner's active brand."},"name":{"type":"string","maxLength":120,"description":"Campaign name."},"startDate":{"oneOf":[{"type":"string","description":"ISO 8601 date or date-time"},{"type":"number","description":"Unix milliseconds"}]},"endDate":{"oneOf":[{"type":"string","description":"ISO 8601 date or date-time"},{"type":"number","description":"Unix milliseconds"}]},"timezone":{"type":"string","description":"IANA timezone, e.g. America/New_York. Default: the workspace's."},"goal":{"type":"string","maxLength":40,"examples":["engagement","sale","launch","holiday","custom"],"description":"Picks the arc phases and default platforms. A goal id from the campaign builder config: built in are \"engagement\", \"sale\", \"launch\", \"holiday\" (admins can add more without a deploy), or \"custom\" with customGoal. Default: \"custom\" when customGoal is set, else the configured default goal (\"engagement\"). Engagement needs no offer, price or deadline."},"customGoal":{"description":"Create your own goal (goal \"custom\"): the goal in the owner's words, used as the campaign goal in every caption prompt. A bare string is the text. Phases follow the closest built-in template (by the config's keywords) unless `template` picks one.","oneOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":1000,"description":"One sentence, e.g. \"Get more people to book a free consultation\"."},"successMeasures":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Success-measure ids from the config: comments, replies, saves, shares, link_clicks, messages, sign_ups, visits, sales."},"template":{"type":"string","enum":["engagement","sale","launch","holiday"],"description":"The built-in template to plan with. Default: the closest one to the text."}}}]},"source":{"type":"string","enum":["store","brand"],"description":"What the posts are built from. \"store\" (default): the featured products. \"brand\": no store needed — the brand kit and voice, the website, the Library and post themes, plus the optional interview. A brand campaign sends no products and needs no offer (set offer.noSale unless it is a deal); it works with any goal, including \"engagement\" and \"custom\"."},"interview":{"type":"object","description":"Brand campaigns only, every answer optional: what the business is promoting or talking about this month, anything coming up, and who the posts are for.","properties":{"promoting":{"type":"string","maxLength":1000,"description":"What are you promoting or talking about this month?"},"upcoming":{"type":"string","maxLength":1000,"description":"Anything coming up?"},"audience":{"type":"string","maxLength":1000,"description":"Who is it for?"}}},"offer":{"type":"object","description":"Required, with a headline, for a store campaign whose goal needs an offer (sale, launch, holiday). Optional for engagement and custom goals, and for a brand campaign (its headline falls back to the \"promoting\" answer, then a configured focus). Captions state when the offer ends only when it has endsAt or a discountPercent (a discount ends with the campaign). startsAt / endsAt are the offer's own days when it runs on only some of the campaign's days (Cyber Week: campaign Mon 11/23 – Tue 12/1, offer Fri 11/27 – Mon 11/30): the teaser and countdown are planned before startsAt, the last-chance post on the day of endsAt and the thank-you after it. Without them the offer days are the campaign's days.","properties":{"headline":{"type":"string","maxLength":200},"discountPercent":{"type":"number","exclusiveMinimum":0,"maximum":100},"code":{"type":"string","maxLength":64},"freeShipping":{"type":"boolean"},"terms":{"type":"string","maxLength":1000},"startsAt":{"oneOf":[{"type":"string","description":"ISO 8601 date or date-time"},{"type":"number","description":"Unix milliseconds"}],"description":"First instant of the offer. Use a date-time with an offset; a bare date is read as UTC midnight."},"endsAt":{"oneOf":[{"type":"string","description":"ISO 8601 date or date-time"},{"type":"number","description":"Unix milliseconds"}],"description":"Last instant of the offer; captions state it as the end. Use a date-time with an offset; a bare date is read as UTC midnight."},"noSale":{"type":"boolean","description":"The campaign is not a sale: captions state no discount, code, free shipping or end, even when those fields are set."}}},"products":{"type":"array","description":"Featured products (at most the configured product cap). Shopify: {source:\"shopify\", productGid}. Others: {source:\"manual\"|\"url\", title, price?, url?, imageUrl?, description?}.","items":{"type":"object","required":["source"],"properties":{"source":{"type":"string","enum":["shopify","manual","url"]},"productGid":{"type":"string","description":"gid://shopify/Product/… (source shopify)."},"title":{"type":"string","maxLength":200},"price":{"type":"number","minimum":0},"compareAtPrice":{"type":"number","minimum":0},"url":{"type":"string","maxLength":2000},"imageUrl":{"type":"string","maxLength":2000},"description":{"type":"string","maxLength":2000}}}},"platforms":{"type":"array","maxItems":10,"items":{"type":"string"},"description":"Platform ids (instagram, tiktok, …). Empty = the configured platforms for the goal."},"overrides":{"type":"object","properties":{"postingHour":{"type":"integer","minimum":0,"maximum":23},"requireReview":{"type":"boolean","description":"Hold booked posts for review before they go live."},"images":{"type":"string","enum":["product_photo","none"]},"phases":{"type":"object","description":"Overrides per arc phase.","properties":{"teaser":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"countdown":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"launch":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"product":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"mid_sale":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"last_chance":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"thank_you":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"warm_up":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"conversation":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}},"follow_up":{"type":"object","properties":{"enabled":{"type":"boolean"},"dayOffset":{"type":"integer","minimum":-60,"maximum":60},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer","minimum":0,"maximum":50}}}}}}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"briefId":{"type":"string"},"slots":{"type":"array","items":{"type":"object","properties":{"phase":{"type":"string"},"role":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"scheduledAt":{"type":"string","format":"date-time"},"past":{"type":"boolean","description":"Already past: no draft is made for it."},"product":{"type":"object","nullable":true}}}},"estimate":{"type":"object","description":"Upper bound of the Embers generation charges. Failed calls are not charged.","properties":{"embers":{"type":"number"},"calls":{"type":"integer"},"unitEmbers":{"type":"number"},"upperBound":{"type":"boolean"},"lines":{"type":"array","items":{"type":"object","properties":{"slotIndex":{"type":"integer"},"phase":{"type":"string"},"feature":{"type":"string"},"calls":{"type":"integer"},"embers":{"type":"number"}}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brandId outside a brand-bound key"},"404":{"description":"Unknown brandId"},"422":{"description":"Bad brief, or the plan does not include organic social campaigns"},"429":{"description":"Rate limit or monthly quota"}}}},"/api/v2/campaigns/builder/{id}/generate":{"post":{"tags":["API v2"],"summary":"Generate a campaign's drafts (charges Embers)","description":"Starts generating a draft for every slot that has none yet. CHARGES EMBERS per caption call (at most `estimate.embers`); refused with 402 up front when the balance cannot cover it. Runs in the background: poll the campaign. Starting again only fills slots still without a draft. Needs `write`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id (from create).","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand to act in. A brand-bound key acts in its own brand (another brandId is 403); an account-wide key defaults to the owner's active brand."}}}}}},"responses":{"200":{"description":"Not started (already running, or nothing left to generate)","content":{"application/json":{"schema":{"type":"object","properties":{"started":{"type":"boolean"},"reason":{"type":"string"},"total":{"type":"integer"},"pending":{"type":"integer"}}}}}},"202":{"description":"Started","content":{"application/json":{"schema":{"type":"object","properties":{"started":{"type":"boolean"},"estimate":{"type":"object","description":"Upper bound of the Embers generation charges. Failed calls are not charged.","properties":{"embers":{"type":"number"},"calls":{"type":"integer"},"unitEmbers":{"type":"number"},"upperBound":{"type":"boolean"},"lines":{"type":"array","items":{"type":"object","properties":{"slotIndex":{"type":"integer"},"phase":{"type":"string"},"feature":{"type":"string"},"calls":{"type":"integer"},"embers":{"type":"number"}}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"insufficient_credits: the Embers balance cannot cover the estimate","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"estimate":{"type":"object","description":"Upper bound of the Embers generation charges. Failed calls are not charged.","properties":{"embers":{"type":"number"},"calls":{"type":"integer"},"unitEmbers":{"type":"number"},"upperBound":{"type":"boolean"},"lines":{"type":"array","items":{"type":"object","properties":{"slotIndex":{"type":"integer"},"phase":{"type":"string"},"feature":{"type":"string"},"calls":{"type":"integer"},"embers":{"type":"number"}}}}}}}}}}},"403":{"description":"Missing scope, or a brandId outside a brand-bound key"},"404":{"description":"Not found, not a builder campaign, or no access"},"429":{"description":"Rate limit or monthly quota"},"503":{"description":"credit_lookup_failed: the balance could not be read; nothing was charged"}}}},"/api/v2/campaigns/builder/{id}/book":{"post":{"tags":["API v2"],"summary":"Book a campaign's drafts","description":"Puts every generated draft into the campaign's own posting queue (labelled `campaign:<id>`, created on first booking), each pinned to its slot time. Posts go live at those times unless review is required. Booking again skips drafts already booked. Drafts too close to their time stay in the campaign. Needs `publish`; Agency plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id (from create).","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand to act in. A brand-bound key acts in its own brand (another brandId is 403); an account-wide key defaults to the owner's active brand."}}}}}},"responses":{"200":{"description":"Booked","content":{"application/json":{"schema":{"type":"object","properties":{"queueId":{"type":"string"},"createdQueue":{"type":"boolean"},"booked":{"type":"integer"},"itemIds":{"type":"array","items":{"type":"string"}},"rejected":{"type":"array","items":{"type":"object"}},"skippedTooSoon":{"type":"array","items":{"type":"string"}},"summary":{"type":"object"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"The key owner's plan does not include the API queue tools"},"403":{"description":"Missing scope, or a brandId outside a brand-bound key"},"404":{"description":"Not found or no access"},"422":{"description":"Nothing to book, or the campaign cannot be booked"},"429":{"description":"Rate limit or monthly quota"}}}},"/api/v2/reviews":{"get":{"tags":["API v2"],"summary":"List scheduled-post reviews","description":"Scheduled posts waiting for (or given) a human sign-off, oldest slot first. A brand-bound key sees its brand; an account-wide key sees every brand it belongs to plus Personal, or one with ?brandId=. `pending` also lists posts whose required-mode hold failed at the platform, and held posts whose slot passed unapproved (`missed`; approve them with `pastSlot`). Each review carries `inWindow` (its slot is within the brand's approval window, default 14 days) and `approvalWindowDays`; `?window=in|upcoming|all` filters on it.","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","approved","held","missed","all"],"default":"pending"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"}},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["in","upcoming","all"],"default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":300}},{"name":"cursor","in":"query","description":"Opaque nextCursor from the previous page. Keep filters unchanged; limit may change. Slot/creation/id ordering avoids offset shifts. New reviews after the first page are excluded; edits and deletions remain live.","schema":{"type":"string"}},{"name":"slotBefore","in":"query","description":"Only slots strictly before this ISO timestamp (timezone required). Undated reviews excluded.","schema":{"type":"string","format":"date-time"}},{"name":"slotAfter","in":"query","description":"Only slots strictly after this ISO timestamp (timezone required). Undated reviews excluded.","schema":{"type":"string","format":"date-time"}},{"name":"postStatus","in":"query","description":"Exact underlying post status, e.g. review_held or missed_review. Rows without a post do not match.","schema":{"type":"string"}},{"name":"includeGone","in":"query","description":"Include cancelled/deleted posts in held/missed results (including status=all). Defaults to false.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"One page of reviews. total counts individual matching reviews per stored status before pagination, using all requested filters (not grouped app cards).","content":{"application/json":{"schema":{"type":"object","properties":{"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Review id."},"postId":{"type":"string","nullable":true,"description":"The post's convexPostId (null for a queue item not booked yet)."},"queueItemId":{"type":"string","nullable":true},"contentId":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","approved","held","missed","hold_failed"]},"postStatus":{"type":"string","nullable":true},"mode":{"type":"string","enum":["optional","required"]},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"caption":{"type":"string"},"thumbnailUrl":{"type":"string","nullable":true},"platforms":{"type":"array","items":{"type":"string"}},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"brandName":{"type":"string"},"reviewer":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true}}},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"error":{"type":"string","nullable":true,"description":"e.g. the platform's refusal when a hold failed."},"canApprove":{"type":"boolean","description":"Whether THIS key may approve it (review scope, not its own post, reviewer-must-differ)."},"approveBlockedReason":{"type":"string","nullable":true}}}},"total":{"type":"object","properties":{"pending":{"type":"integer","minimum":0},"approved":{"type":"integer","minimum":0},"held":{"type":"integer","minimum":0},"missed":{"type":"integer","minimum":0},"hold_failed":{"type":"integer","minimum":0}}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}},"403":{"description":"Missing read scope, or another brand for a bound key"},"422":{"description":"Invalid filters, limit, date range, or cursor"}}}},"/api/v2/reviews/bulk":{"post":{"tags":["API v2"],"summary":"Discard or hold up to 100 scheduled-post reviews","description":"Needs review or publish, on the same plan as a single review decision. Never approves. IDs may be review ids or convexPostIds; duplicates are processed once. Each id is checked independently for ownership, brand and state. Discard cancels for good, preserving content; an already-rejected collab can be discarded. Hold keeps the post in Held (for collabs it rejects the caller’s side; ambiguous sides are skipped). One request counts once against the IP and API request limits. dryRun reads eligibility only: no review changes, notifications or platform calls. requiresUnschedule means execution also depends on platform acceptance. A legacy collab needing approval attachment is skipped in the preview. closed counts successful (or would-succeed) decisions, including holds; skipped includes already-discarded posts. A dry run is a snapshot, not a reservation.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","decision"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^[a-z0-9]{10,64}$"}},"decision":{"type":"string","enum":["discard","hold"]},"note":{"type":"string","maxLength":1000},"dryRun":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Per-id outcomes, including partial failures.","content":{"application/json":{"schema":{"type":"object","required":["decision","dryRun","closed","skipped","results"],"properties":{"decision":{"type":"string","enum":["discard","hold"]},"dryRun":{"type":"boolean"},"closed":{"type":"integer"},"skipped":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["id","result"],"properties":{"id":{"type":"string"},"result":{"type":"string","enum":["discarded","held","would_discard","would_hold","skipped"]},"code":{"type":"string"},"error":{"type":"string"},"requiresUnschedule":{"type":"boolean"}}}}}}}}},"401":{"description":"Invalid key"},"402":{"description":"Plan gate"},"403":{"description":"Missing review or publish scope"},"422":{"description":"Invalid body"},"429":{"description":"Request rate limit or monthly quota"}}}},"/api/v2/reviews/{id}":{"post":{"tags":["API v2"],"summary":"Approve, hold or discard a scheduled post","description":"Approving needs the explicit `review` scope (admin does NOT include it) and never works for a post the same key created; with the brand's reviewer-must-differ setting the key owner cannot approve their own post. Approving a post held in flayr (required mode) sends it to the platform for its slot (or right away when the slot is under 2 minutes out); after the slot it is 409 `slot_passed` unless `pastSlot` says what to do: \"now\" posts it right away, { at } books a new future time. Hold (review or publish scope) takes a post off the platform schedule; if the platform refuses (some YouTube posts), the response is 502 with platformError and the post stays scheduled. Discard cancels a held or waiting post for good (content stays), with status cancelled and discarded: true. A rejected collab may be discarded; pending and approved collabs must be decided per brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A convexPostId or a review id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","hold","discard"]},"note":{"type":"string","maxLength":1000},"pastSlot":{"description":"Only for a held post whose slot passed: \"now\", or { at: ISO-8601 future time }.","oneOf":[{"type":"string","enum":["now"]},{"type":"object","required":["at"],"properties":{"at":{"type":"string","format":"date-time"}}}]},"collabSide":{"type":"string","enum":["owner","grantee"],"description":"FFE-501 collab posts only: which brand this decision is for (\"owner\" = the shared character's brand, \"grantee\" = the brand that made the post). Needed only when the key's owner approves for both brands; a brand-bound key always decides for its own brand. A collab post publishes only after BOTH sides approved; \"hold\" rejects it for good."}}}}}},"responses":{"200":{"description":"{ reviewId, status, sent?, scheduled?, postIds? }"},"403":{"description":"Scope or reviewer rules"},"404":{"description":"Not found (or another brand for a bound key)"},"409":{"description":"`slot_passed` (choose pastSlot), or already decided"},"422":{"description":"Invalid body"},"502":{"description":"The platform refused to unschedule the post (platformError)"}}}},"/api/v2/reviews/move":{"post":{"tags":["API v2"],"summary":"Move held posts to another slot (one or many)","description":"Moving never approves: the post stays, or if Missed/Held goes back to, pending review. Only posts held in flayr move here; a post already booked at the platform answers `vendor_booked` (PATCH /api/v2/posts/{id} moves it). Needs the `review` or `publish` scope. Each item reports its own result.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","to"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"Review ids or convexPostIds."},"to":{"type":"object","description":"Exactly one of: { at: ISO-8601 }; { shiftDays, shiftMinutes? } from each post's own slot; { date: \"YYYY-MM-DD\", time?: \"HH:mm\", timeZone } that day, at `time` or each post's own time of day.","properties":{"at":{"type":"string","format":"date-time"},"shiftDays":{"type":"integer"},"shiftMinutes":{"type":"integer"},"date":{"type":"string"},"time":{"type":"string"},"timeZone":{"type":"string"}}}}}}}},"responses":{"200":{"description":"{ results: [{ id, ok, reviewId?, from?, to?, reopened?, accountSwapped?: { platform, from, to }, accountSwaps?, code?, error? }], moved, failed }"},"403":{"description":"Scope"},"422":{"description":"Invalid body"}}}},"/api/v2/collab/grants":{"get":{"tags":["API v2"],"summary":"List collab shares of a brand","description":"Character and voice shares of one brand, both directions (outgoing = shared by it, incoming = shared with it). A brand-bound key reads its brand; an account-wide key names ?brandId=. Needs read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ outgoing: [...], incoming: [...] }"},"403":{"description":"Another brand for a bound key"},"422":{"description":"brandId missing for an account-wide key"}}},"post":{"tags":["API v2"],"summary":"Share a character or voice with another brand","description":"Lend a character (the other brand gets a linked, read-only copy it generates with, on its own Embers) or a cloned voice, until it expires (admin config: default 30, max 90 days) or is revoked. Every post made with it needs approval from BOTH brands. The key owner must be an owner/admin of the character's brand. Re-sharing a live share renews it. Needs write.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","granteeBrandId"],"properties":{"subject":{"type":"string","enum":["character","voice"]},"characterId":{"type":"string"},"voiceCloneId":{"type":"string"},"granteeBrandId":{"type":"string","description":"The other brand's id (its collab ID)."},"expiresInDays":{"type":"integer","minimum":1},"scopes":{"type":"array","items":{"type":"string","enum":["still","clip","talking","voice"]}},"note":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"{ grantId, granteeCharacterId?, renewed }"},"403":{"description":"Not an owner/admin of the brand"},"404":{"description":"Character / voice / brand not found"},"422":{"description":"Invalid terms"}}}},"/api/v2/collab/grants/{id}":{"delete":{"tags":["API v2"],"summary":"Stop a collab share","description":"Revoke now: nothing new can be made with it, and its collab posts still waiting for approval are rejected and held. Needs write.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ revoked }"},"403":{"description":"Not an owner/admin of the owner brand"},"404":{"description":"Share not found"}}}},"/api/v2/collab/approvals":{"get":{"tags":["API v2"],"summary":"List collab posts waiting for approval","description":"Collab posts the key owner approves for, on either side. Decide with POST /api/v2/reviews/{reviewId} (collabSide when needed). Needs read.","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","approved","rejected"],"default":"pending"}},{"name":"side","in":"query","required":false,"schema":{"type":"string","enum":["owner","grantee","any"],"default":"any"}}],"responses":{"200":{"description":"{ approvals: [...] }"},"422":{"description":"Invalid status or side"}}}},"/api/v2/approval-groups":{"get":{"tags":["API v2"],"summary":"List content waiting for approval, one group per piece","description":"The variants waiting on the key owner's decision, grouped by piece, with the axes they vary on, a tally and each variant's state and `slot:` time. Decided variants of the same draft are included so the tally is complete. A group is the variants of one piece: content that shares a `draftGroupId` (one group per brand). Fallback: content with no `draftGroupId` groups by a `group:<id>` label (e.g. `group:spring-launch`); a `group:` group holds only the variants in your pending list (at most 50). A group needs at least 2 variants; a group above the variant cap (120) is split into `#2`, `#3` … parts. The group id is `dg:<draftGroupId>@<brandId>` or `lbl:<label id>@<brandId>` (no `@…` for personal content); URL-encode it in the path. `status` (default open) keeps groups that have a variant in that state; `all` keeps every group. Needs an API key with the explicit `approve` scope (admin does NOT include it) on the Agency plan; a brand-bound key sees and decides only its brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brand","in":"query","required":false,"schema":{"type":"string"},"description":"\"personal\" or a brand id (`brandId` is accepted too)."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","redo","approved","dropped","all"],"default":"open"}}],"responses":{"200":{"description":"Groups","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"groupId":{"type":"string"},"draftGroupId":{"type":"string","nullable":true,"description":"Null for a `group:` label group."},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"brandName":{"type":"string","nullable":true},"axes":{"type":"array","description":"The label keys whose values differ across the variants (theme, open, audio, dt, hook, cta, cut, then any other), with their values.","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}}},"tally":{"type":"object","properties":{"approved":{"type":"integer"},"redo":{"type":"integer"},"dropped":{"type":"integer"},"open":{"type":"integer"}}},"slotFrom":{"type":"string","format":"date-time","nullable":true,"description":"Earliest `slot:` label time."},"slotTo":{"type":"string","format":"date-time","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"approvalId":{"type":"string"},"contentId":{"type":"string"},"state":{"type":"string","enum":["open","approved","redo","dropped"]},"labels":{"type":"array","items":{"type":"string"}},"slotAt":{"type":"string","format":"date-time","nullable":true},"caption":{"type":"string","description":"Caption preview (≤ 280 chars)."},"platforms":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"402":{"description":"Plan below Agency"},"403":{"description":"Missing approve scope, or another brand for a bound key"},"422":{"description":"Invalid status"}}}},"/api/v2/approval-groups/{groupId}/decide":{"post":{"tags":["API v2"],"summary":"Approve, redo or drop variants of one piece","description":"Decides the chosen OPEN variants of a group, one single decision each with the rules of POST /api/v2/approvals/{id} (only the assigned approver; the org's reject-reason rule). Already-decided variants are skipped, never decided twice. `approve` marks a variant approved — like the single route it does NOT post a manual approval (publish it with POST /api/v2/publish `contentId`; its `slot:` label is the time) and resumes a parked workflow run. `redo` rejects with the `Redo` reason (the submitter re-makes it); `drop` rejects (the optional `note` is the reason). Labels, `slot:` included, are never changed. Needs an API key with the explicit `approve` scope (admin does NOT include it) on the Agency plan; a brand-bound key sees and decides only its brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"A groupId from GET /api/v2/approval-groups."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","redo","drop"]},"members":{"description":"\"all\" (default): every open variant. An array: those approval ids. An object: the variants whose labels match every axis value, e.g. {\"audio\":\"voice\"}.","oneOf":[{"type":"string","enum":["all"]},{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500},{"type":"object","additionalProperties":{"type":"string"}}]},"note":{"type":"string","maxLength":1000,"description":"On drop/redo: the reason. Optional unless the org requires one."}}}}}},"responses":{"200":{"description":"{ groupId, decision, results: [{ approvalId, ok, alreadyDecided?, code?, error? }], done, failed, skipped }"},"402":{"description":"Plan below Agency"},"403":{"description":"Missing approve scope"},"404":{"description":"Group not found (or another brand for a bound key)"},"422":{"description":"Invalid body, or no variant matches `members`"}}}},"/api/v2/approvals":{"get":{"tags":["API v2"],"summary":"List content waiting for your approval (or rejected)","description":"Content held for approval that waits on the key owner's decision, newest first (at most 50): posts filed with POST /api/v2/publish `requiresApproval: true`, drafts submitted for review, and workflow runs parked at an approval gate. `status=rejected` lists rejections instead (the ones the key owner asked for, was assigned, or may decide as an org owner/admin), newest first, with the reason, who rejected and when; the rows have the rejected shape. A brand-bound key sees its brand; an account-wide key sees every brand, or one with ?brandId=. Needs an API key with the explicit `approve` scope (admin does NOT include it) on the Agency plan. With the `approvals:decide` scope the inbox also holds ad budget and ceiling requests your agents filed above your ceiling (`kind: \"ad_budget\"`), when the key owner is owner/admin of the key's workspace and has Ads (no Agency plan needed). A key never sees or decides a request it filed itself.","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","rejected"],"default":"pending"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Approvals (the rejected shape for status=rejected)","content":{"application/json":{"schema":{"type":"object","properties":{"approvals":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Approval id (the `approvalId` POST /api/v2/publish returned)."},"contentId":{"type":"string"},"status":{"type":"string","enum":["pending"]},"kind":{"type":"string","enum":["manual","workflow"],"description":"`workflow`: a run parked at an approval gate; approving resumes it."},"runId":{"type":"string","nullable":true},"workflowName":{"type":"string","nullable":true},"requestedBy":{"type":"string","description":"User id that asked for approval."},"requestedByThisUser":{"type":"boolean","description":"Whether the key owner filed it themselves."},"requestedAt":{"type":"string","format":"date-time"},"caption":{"type":"string","description":"Caption preview."},"platforms":{"type":"array","items":{"type":"string"}},"contentType":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"brandName":{"type":"string","nullable":true}}},{"type":"object","properties":{"id":{"type":"string","description":"The request id (decide it with POST /api/v2/approvals/{id})."},"status":{"type":"string","enum":["pending"]},"kind":{"type":"string","enum":["ad_budget"]},"action":{"type":"string","description":"set_caps, set_spend_limit, scale_campaign, activate_campaign, …"},"title":{"type":"string"},"agentName":{"type":"string"},"reason":{"type":"string","description":"The agent's stated reason."},"targetId":{"type":"string","nullable":true},"amountMinor":{"type":"integer","nullable":true,"description":"The amount asked for, in cents (null: e.g. removing a spending limit)."},"amount":{"type":"string","nullable":true,"description":"amountMinor formatted, e.g. \"$1,200.00\"."},"ceilingMinor":{"type":"integer","nullable":true,"description":"The agent ceiling it is above."},"changes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"beforeMinor":{"type":"integer","nullable":true},"afterMinor":{"type":"integer","nullable":true}}}},"summary":{"type":"string","description":"One line before → after, e.g. \"Monthly ad spend cap: $500.00 → $1,200.00\"."},"confirmRequired":{"type":"boolean","description":"The workspace requires approve to restate the amount (`confirmAmountMinor`)."},"requestedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"id":{"type":"string","description":"The rejected approval id (resubmit with POST /api/v2/approvals/{id}/resubmit)."},"contentId":{"type":"string"},"status":{"type":"string","enum":["rejected"]},"contentExists":{"type":"boolean","description":"False when the content was deleted on reject."},"caption":{"type":"string","description":"Caption preview."},"note":{"type":"string","nullable":true,"description":"The reviewer's reason (null when none was given)."},"reasonChips":{"type":"array","items":{"type":"string"},"description":"The one-tap reasons the reviewer picked."},"rejectedBy":{"type":"string","nullable":true,"description":"User id that rejected it."},"rejectedAt":{"type":"string","format":"date-time","nullable":true},"requestedBy":{"type":"string","description":"User id that asked for approval."},"requestedByThisUser":{"type":"boolean"},"approverId":{"type":"string","description":"The approver a resubmission goes to."},"resubmitted":{"type":"boolean","description":"Whether it was already sent back for review."},"brandId":{"type":"string","description":"\"personal\" or a brand id."}}}]}}}}}}},"402":{"description":"Plan below Agency"},"403":{"description":"Missing approve scope, or another brand for a bound key"},"422":{"description":"Invalid status"}}}},"/api/v2/approvals/bulk":{"post":{"tags":["API v2"],"summary":"Reject or archive many pending approvals","description":"The cleanup path for a stale approval queue (FFE-1329). `reject` is the single reject, per id: content back to draft, a parked workflow run cancelled, the submitter notified once per approval. `archive` closes the approval and archives its content (restorable from Library → Archive); only the content's owner or an org owner/admin may archive, and `note` is ignored. Each id is decided on its own: one that is not found, not yours, another brand's or already decided is reported as `skipped` and left as it was. `dryRun: true` reports what would close and writes nothing. Pending approvals also close on their own as `expired` once they are older than the org's `expireAfterDays` (default 7, 0 = never) and their planned slot has passed. Needs an API key with the explicit `approve` scope (admin does NOT include it) on the Agency plan.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","action"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"}},"action":{"type":"string","enum":["reject","archive"]},"note":{"type":"string","maxLength":1000,"description":"On reject: the reason. Optional unless the org requires one."},"dryRun":{"type":"boolean"}}}}}},"responses":{"200":{"description":"{ action, dryRun, closed, skipped, results: [{ id, result: \"rejected\" | \"archived\" | \"would_reject\" | \"would_archive\" | \"skipped\", contentId?, code?, error? }] }"},"402":{"description":"Plan below Agency"},"403":{"description":"Missing approve scope"},"422":{"description":"Invalid body"}}}},"/api/v2/approvals/{id}":{"post":{"tags":["API v2"],"summary":"Approve or reject content held for approval","description":"Same rules and effect as deciding in the dashboard: only the assigned approver may decide. Manual approvals: approve marks the content approved WITHOUT posting it (publish it with POST /api/v2/publish `contentId`); reject returns it to draft. Workflow approvals: approve resumes the parked run (its next steps may publish), reject cancels it. Repeating the same decision returns 200 with `alreadyDecided: true`; the opposite decision is 409. On reject, `note` is the reason the submitter is told (they are notified with it). It is optional unless the org requires a reason (an org setting with a minimum length); then a reject without one, or with one too short, is 422. Needs an API key with the explicit `approve` scope (admin does NOT include it) on the Agency plan. Ad budget requests (`kind: \"ad_budget\"`, `approvals:decide` scope): approving caps applies them now; any other action lets the agent repeat its exact call once within 7 days. When the workspace requires money confirmation, approve must send `confirmAmountMinor` equal to the request's `amountMinor` (null when it has none), else 409 `confirmation_required` with the before → after. Answer: { approvalId, kind, action, status, alreadyDecided, effect, amountMinor, changes, summary, next }. Audited with who, when, the surface and the key.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An approval id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject"]},"note":{"type":"string","maxLength":1000,"description":"On reject: the reason. Optional unless the org requires one."},"confirmAmountMinor":{"type":"integer","nullable":true,"minimum":0,"description":"Ad budget requests only: restate `amountMinor` (cents; null when it is null) when the workspace requires money confirmation."}}}}}},"responses":{"200":{"description":"{ approvalId, contentId, status, alreadyDecided, runId, effect }"},"402":{"description":"Plan below Agency"},"403":{"description":"Missing approve scope, or not the assigned approver"},"404":{"description":"Not found (or another brand for a bound key)"},"409":{"description":"Already decided the other way, an expired ad request, or `confirmation_required`"},"422":{"description":"Invalid body, or a reject without the reason the org requires"}}}},"/api/v2/approvals/{id}/resubmit":{"post":{"tags":["API v2"],"summary":"Resubmit rejected content for approval","description":"Sends a rejected piece back for review, usually after editing it (PATCH /api/v2/content/{id}). Files a NEW pending approval for the same approver; the rejected approval stays as the record. Nothing is published or scheduled. Who may: whoever asked for the approval, its approver or decider, or an org owner/admin who may decide it. Needs an API key with the explicit `approve` scope (admin does NOT include it) on the Agency plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A rejected approval id (GET /api/v2/approvals?status=rejected)."}],"responses":{"201":{"description":"{ approvalId, contentId, previousApprovalId, status: \"pending\" }"},"402":{"description":"Plan below Agency"},"403":{"description":"Missing approve scope"},"404":{"description":"Not found, not yours, or another brand for a bound key"},"409":{"description":"Not rejected, the content is gone or published, or an approval is already pending for it"}}}},"/api/v2/approvals/{id}/regenerate":{"post":{"tags":["API v2"],"summary":"Re-generate rejected content from the reviewer's reason","description":"Estimate first: without `confirm: true` it returns the Embers cost and makes no model call and no charge. With `confirm: true` it rewrites the post text with the reason as feedback, saves it as a NEW draft in the same draft group (labelled `variant:regen-<n>`) and files one pending approval for the same approver. Only the text is re-generated; media is kept. The rejected approval is unchanged. Nothing is published or scheduled. Embers are charged once, after the draft is saved; a failed model call or save charges nothing. Who may: as for resubmit. Needs an API key with the explicit `approve` scope (admin does NOT include it) on the Agency plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A rejected approval id (GET /api/v2/approvals?status=rejected)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","description":"true to spend the Embers and re-generate; omit for the estimate."}}}}}},"responses":{"200":{"description":"{ estimate: { embers, remaining, enough }, nextLabel, feedback } (no confirm: nothing spent)"},"201":{"description":"{ approvalId, contentId, label, credits, status: \"pending\" }"},"400":{"description":"Invalid JSON, or confirm is not a boolean"},"402":{"description":"Plan below Agency, or not enough Embers"},"403":{"description":"Missing approve scope"},"404":{"description":"Not found, not yours, or another brand for a bound key"},"409":{"description":"Not rejected, the content is gone or published, or an approval is already pending for it"},"422":{"description":"The content has no text to re-generate"},"502":{"description":"The model call failed (nothing charged)"}}}},"/api/v2/approvals/move":{"post":{"tags":["API v2"],"summary":"Move held content to another time (one or many)","description":"Rewrites the `slot:` time of content waiting for approval. Moving never approves and books nothing. Other labels are kept. Workflow approvals and already-booked content answer per item with a code. Each item reports its own result, so one bad id never blocks the rest. Needs an API key with the explicit `approve` scope (admin does NOT include it) on the Agency plan.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","to"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"}},"to":{"type":"object","description":"Exactly one of: { at: ISO-8601 }; { shiftDays, shiftMinutes? } from each item's own time; { date: \"YYYY-MM-DD\", time?: \"HH:mm\", timeZone } that day, at `time` or each item's own time of day.","properties":{"at":{"type":"string","format":"date-time"},"shiftDays":{"type":"integer"},"shiftMinutes":{"type":"integer"},"date":{"type":"string"},"time":{"type":"string"},"timeZone":{"type":"string"}}}}}}}},"responses":{"200":{"description":"{ results: [{ id, ok, approvalId?, from?, to?, code?, error? }], moved, failed }"},"403":{"description":"Missing the approve scope"},"422":{"description":"Invalid body"}}}},"/api/v2/failed":{"get":{"tags":["API v2"],"summary":"List the Failed tab (failed post platforms)","description":"The Schedule → Failed backlog: one row per platform of a post that did not go out, oldest slot first per state. `state=open` (default) is pending then retrying, what the Failed tab shows. Rows come from the backlog only: a failure the dashboard still reads straight off a recent post, before it has a row, is not listed. A page may hold fewer than `limit` rows (filters apply inside it); follow `cursor` until it is null. A brand-bound key works in its own brand; an account-wide key names one with `brandId` (\"personal\" or an id from GET /api/v2/brands; omitted = its active brand). Needs the `read` scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["open","pending","retrying","dismissed","resolved"],"default":"open"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string"}},{"name":"zernioAccountId","in":"query","required":false,"schema":{"type":"string"}},{"name":"reasonClass","in":"query","required":false,"schema":{"type":"string","enum":["auth_or_account","content","transient","unknown"]}},{"name":"slotAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only rows whose slot is at or after this instant (ISO 8601 with an offset)."},{"name":"slotBefore","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only rows whose slot is before this instant."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `cursor` of the previous page."}],"responses":{"200":{"description":"One page of rows","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Row id: what POST /api/v2/failed/dismiss takes."},"postId":{"type":"string"},"contentId":{"type":"string","nullable":true},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"platform":{"type":"string"},"account":{"type":"object","properties":{"zernioAccountId":{"type":"string","nullable":true},"name":{"type":"string","nullable":true,"description":"The account's display name or username, when the post recorded one."}}},"slotAt":{"type":"string","format":"date-time","nullable":true,"description":"When the post was meant to go out."},"failedAt":{"type":"string","format":"date-time"},"lastError":{"type":"string"},"reasonClass":{"type":"string","enum":["auth_or_account","content","transient","unknown"]},"state":{"type":"string","enum":["pending","retrying","dismissed","resolved"]},"attempts":{"type":"integer"},"disconnected":{"type":"boolean","description":"The failure was an account disconnect."},"postStatus":{"type":"string","nullable":true,"description":"The post's own status now."},"coverage":{"type":"string","enum":["live","rebooked"],"nullable":true,"description":"`live`: the post went out on this platform after all, or another post of the same content is published there. `rebooked`: another post of the same content is booked there. null: nothing known covers it."},"dismissedAt":{"type":"string","format":"date-time","nullable":true},"dismissedBy":{"type":"string","nullable":true,"description":"A user id, or \"apikey:<keyId>\" for a dismiss through this API."}}}},"cursor":{"type":"string","nullable":true},"isDone":{"type":"boolean"}}}}}},"403":{"description":"Missing read scope, or another brand for a bound key"},"404":{"description":"Brand not found"},"422":{"description":"Invalid filter or cursor"}}}},"/api/v2/failed/dismiss":{"post":{"tags":["API v2"],"summary":"Dismiss Failed-tab rows by id","description":"Closes named rows of the Failed backlog, the same Dismiss as the dashboard: for stale rows (already live, rebooked, or no longer wanted). Dismiss only closes the backlog row; the post, its status and any live booking are never touched. Each id is decided on its own: one that is not found, another brand's, already closed, or being retried right now is reported as `skipped` and left as it was. A brand viewer cannot dismiss. `dryRun: true` reports what would close and writes nothing. A brand-bound key works in its own brand; an account-wide key names one with `brandId` (\"personal\" or an id from GET /api/v2/brands; omitted = its active brand). Needs the `write` scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rowIds"],"properties":{"rowIds":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"string"},"description":"Row ids from GET /api/v2/failed."},"brandId":{"type":"string"},"dryRun":{"type":"boolean"}}}}}},"responses":{"200":{"description":"{ dryRun, dismissed, skipped, results: [{ id, result: \"dismissed\" | \"would_dismiss\" | \"skipped\", postId?, platform?, code?: \"not_found\" | \"forbidden\" | \"closed\" | \"leased\", error? }] }"},"403":{"description":"Missing write scope, or another brand for a bound key"},"404":{"description":"Brand not found"},"422":{"description":"Invalid body"}}}},"/api/v2/opus/projects":{"get":{"tags":["API v2"],"summary":"List linked Opus Clip projects","description":"Opus Clip projects tracked in a brand (brand-bound key: its brand; account-wide key: ?brandId=, else the last active brand; required for an account in more than one organization). Needs the read scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string","example":"P3092513WDOp"},"title":{"type":"string"},"source":{"type":"string","enum":["library","upload","url","external"]},"stage":{"type":"string","description":"Opus stage: PENDING, QUEUED, IMPORT, CURATE, REFINE, RENDER, UPLOAD, COMPLETE, STALLED."},"error":{"type":"string","nullable":true},"clipsImported":{"type":"number"},"autoImport":{"type":"boolean","description":"flayr will import the clips itself when Opus finishes."},"lastSyncedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"brandId":{"type":"string","description":"\"personal\" or a brand id."}}}}}}}}},"403":{"description":"Missing read scope, or another brand for a bound key"},"404":{"description":"Unknown brandId"}}},"post":{"tags":["API v2"],"summary":"Link (and import) Opus Clip projects","description":"Links projects that already exist in the key owner's Opus Clip account, checked against Opus with the brand's connected Opus key. `projectIds` takes ids or Opus links (deduped, at most 25). With `import: true`, finished projects' clips are imported as Library drafts; clips already imported are skipped (deduped by Opus clip id), so repeating a call adds nothing. Unfinished projects are imported automatically once Opus completes them. Needs the write (or admin) scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectIds"],"properties":{"projectIds":{"type":"array","items":{"type":"string"},"maxItems":25},"brandId":{"type":"string","description":"\"personal\" or an id from GET /api/v2/brands."},"import":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"{ results: [{ projectId, outcome: linked|already_linked|not_found|error, title?, stage?, error?, imported? }], linked, alreadyLinked, failed, invalid, duplicates }"},"403":{"description":"Missing write scope, or another brand for a bound key"},"404":{"description":"Unknown brandId"},"409":{"description":"No Opus Clip key connected for the brand"},"422":{"description":"Invalid body"}}}},"/api/v2/opus/submit":{"post":{"tags":["API v2"],"summary":"Send a video to Opus Clip","description":"Starts a NEW Opus Clip project in the key owner's Opus account (the brand's connected Opus key, falling back to the personal one) and tracks it in flayr: when Opus finishes, its clips are imported into the brand's Library as drafts automatically (Opus completion webhook, with a background poll as backup). Pass exactly one source: `videoUrl`, a public https link Opus imports itself (YouTube, Google Drive, Vimeo, Loom, Dropbox, ... or a public mp4 URL, up to 10GB), or `videoStorageId`, a file uploaded via POST /api/v2/media/upload-url. Optional `title` (at most 120 characters, default \"Untitled video\") and `brandTemplateId` (an Opus brand template id). Brand: a brand-bound key always uses its own brand; an account-wide key names one with `brandId`, else the last active brand (required for an account in more than one organization). No Embers are charged (Opus Clip is bring-your-own-key). Shares the hourly Opus send limit with the dashboard's \"Send to Opus\". Poll GET /api/v2/opus/projects for the stage and clipsImported. Needs the write (or admin) scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoUrl":{"type":"string","format":"uri","maxLength":2048,"description":"Public https video link. Exclusive with videoStorageId."},"videoStorageId":{"type":"string","description":"storageId from POST /api/v2/media/upload-url. Exclusive with videoUrl."},"brandId":{"type":"string","description":"\"personal\" or an id from GET /api/v2/brands."},"title":{"type":"string","maxLength":120},"brandTemplateId":{"type":"string","description":"Opus brand template id (as in the Opus app)."}}},"example":{"videoUrl":"https://www.youtube.com/watch?v=LXvv6CbGg8A","brandId":"personal","title":"Podcast ep 12"}}}},"responses":{"202":{"description":"Project created; Opus is processing it","content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","example":"P3092513WDOp"},"status":{"type":"string","description":"Opus stage at creation, usually QUEUED."},"brandId":{"type":"string","nullable":true,"description":"\"personal\" or the brand id the project is tracked in."}}}}}},"400":{"description":"Body is not JSON"},"403":{"description":"Missing write scope, or another brand for a bound key"},"404":{"description":"Unknown brandId"},"409":{"description":"No Opus Clip key connected for the brand"},"422":{"description":"Invalid body (no source, both sources, non-https/non-public videoUrl, unknown videoStorageId)"},"429":{"description":"Rate limited"},"502":{"description":"Opus Clip refused or failed to create the project"}}}},"/api/v2/auto-clips/submit":{"post":{"tags":["API v2"],"summary":"Cut a long video into short clips (Auto clips)","description":"Queues an Auto clips job: flayr transcribes the video, picks the 3-5 best moments and saves each as a captioned Library DRAFT that keeps the original shape by default (optional portrait fits the full frame) (nothing is posted). English speech; videos up to 60 minutes and 2 GB. Pass exactly one source: `contentId`, a Library video, or `videoStorageId`, a file uploaded via POST /api/v2/media/upload-url (it is first saved as a Library draft so the clips have a parent). Arbitrary video URLs are not accepted. Paid in Embers from the brand's pool: up to 15 per started minute of source plus 30 per clip. The quote is reserved up front and is a ceiling; you pay only for the minutes processed and clips made, and a failed job is refunded. Pass `durationSeconds` for the tightest quote; without it the quote assumes 45 MB per minute of the file size. Brand: a brand-bound key always uses its own brand; an account-wide key may name one with `brandId`, otherwise the video's own brand is used. Shares the hourly Auto clips limit with the dashboard. Poll GET /api/v2/auto-clips/{jobId}. Needs the write (or admin) scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string","maxLength":200,"description":"A Library video id. Exclusive with videoStorageId."},"videoStorageId":{"type":"string","maxLength":200,"description":"storageId from POST /api/v2/media/upload-url. Exclusive with contentId."},"maxClips":{"type":"integer","minimum":3,"maximum":5,"default":5,"description":"Most clips to make."},"outputFormat":{"type":"string","enum":["source","portrait"],"default":"source","description":"Keep the original shape, or fit the whole video inside a 9:16 canvas without cropping."},"durationSeconds":{"type":"number","minimum":1,"maximum":3600,"description":"The video's length in seconds, for the quote. Omit to quote on the file size."},"brandId":{"type":"string","description":"\"personal\" or an id from GET /api/v2/brands."}}},"example":{"contentId":"k57abc123def456","maxClips":5,"durationSeconds":211}}}},"responses":{"202":{"description":"Job queued; Embers reserved","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["queued"]},"embersQuoted":{"type":"integer","description":"Embers reserved: the most this job can cost."},"brandId":{"type":"string","description":"\"personal\" or the brand id the job runs (and is paid) in."}}}}}},"400":{"description":"Body is not JSON","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Not enough Embers for the quote (or the balance could not be checked)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_credits","credit_check_unavailable"]},"required":{"type":"number"},"available":{"type":"number"},"remaining":{"type":"number"},"message":{"type":"string"},"contentId":{"type":"string","description":"For a videoStorageId source: the Library draft created for it; retry with this contentId."}}}}}},"403":{"description":"Missing write scope, another brand for a bound key, or Auto clips is not available on this account yet"},"404":{"description":"Unknown brandId, or a video the key cannot reach"},"413":{"description":"Over the caps (60 minutes, 2 GB)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["source_too_long","source_too_large"]}}}}}},"422":{"description":"Invalid body (no source, both sources, a videoUrl, maxClips outside 3-5, durationSeconds outside 1-3600, unknown videoStorageId, or no size to quote on)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limited"}}}},"/api/v2/auto-clips/{jobId}":{"get":{"tags":["API v2"],"summary":"Get an Auto clips job","description":"Status of one Auto clips job: its stage, the clips made so far (Library draft ids with their topic), the Embers reserved and, once settled, charged. A job outside the key's reach (another account, or another brand for a brand-bound key) is a 404. Needs the read scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","cancelled"]},"stage":{"type":"string","enum":["preparing","ready","transcribing","selecting","rendering","finalizing","done"]},"clips":{"type":"array","items":{"type":"object","properties":{"contentId":{"type":"string","description":"The clip's Library draft."},"topic":{"type":"string","nullable":true}}}},"embersQuoted":{"type":"integer"},"embersCharged":{"type":"integer","nullable":true,"description":"Embers debited for this job: null until reserved, the reservation while it runs, the final charge once completed. A failed job is refunded in full."},"error":{"type":"string","description":"Present on a failed job."}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing read scope"},"404":{"description":"No such job for this key"}}}},"/api/v2/content/{id}/transcribe":{"post":{"tags":["API v2"],"summary":"Transcribe a Library audio or video item","description":"Queues the same Transcribe run as the Library button: word-timed speech to text, brand terms applied, saved to the item. Read the result as `transcript` on GET /api/v2/content/{id}. Paid in Embers from the item's brand pool: the admin price per started minute of `durationSeconds`, charged when the job starts and refunded in full if it fails. A file longer than `durationSeconds` fails and is refunded; quote again with the real length. Pass `embersQuoted` to refuse a price above it. If a run is already going for the item it is returned (`existing: true`) and nothing is charged twice. Media up to 60 minutes. Poll GET /api/v2/content/{id}/transcribe. Needs the write (or admin) scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["durationSeconds"],"additionalProperties":false,"properties":{"durationSeconds":{"type":"number","minimum":1,"maximum":3600,"description":"The media's length in seconds, for the quote."},"embersQuoted":{"type":"integer","minimum":0,"description":"The most you accept to pay. A higher price is a 409."}}},"example":{"durationSeconds":95,"embersQuoted":10}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["queued"]},"embersQuoted":{"type":"integer","description":"The price of this run."},"existing":{"type":"boolean","description":"true when a run already going for this item was returned."},"brandId":{"type":"string","description":"\"personal\" or the brand id the job runs (and is paid) in."}}}}}},"400":{"description":"Body is not JSON","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Not enough Embers for the quote (or the balance could not be checked)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Missing write scope, or Transcribe is not available on this account yet"},"404":{"description":"No such item for this key"},"409":{"description":"The price is above `embersQuoted`; nothing was queued","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["quote_changed"]},"message":{"type":"string"},"required":{"type":"integer"},"quoted":{"type":"integer"}}}}}},"422":{"description":"Invalid body, not an audio or video item, or no media file","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limited"}}},"get":{"tags":["API v2"],"summary":"List an item's Transcribe runs","description":"The item's newest Transcribe runs (up to 10), newest first, with their status and Embers. Needs the read scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Runs","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"jobId":{"type":"string"},"contentId":{"type":"string"},"mediaKind":{"type":"string","enum":["audio","video"]},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"stage":{"type":"string","enum":["preparing","ready","transcribing","done"]},"quotedSeconds":{"type":"number"},"measuredSeconds":{"type":"number","nullable":true},"embersQuoted":{"type":"integer"},"embersCharged":{"type":"integer","nullable":true,"description":"null until charged; a failed job is refunded in full."},"refundedEmbers":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true},"createdAt":{"type":"integer","description":"Epoch ms."},"completedAt":{"type":"integer","nullable":true,"description":"Epoch ms."}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing read scope"},"404":{"description":"No such item for this key"}}}},"/api/v2/pronunciations":{"get":{"tags":["API v2"],"summary":"List pronunciations","description":"The pronunciation lexicon of a brand (or Personal): `pronunciations` every voice applies, `suggested` learned suggestions (inert until accepted with PATCH or upsert, dismissed with DELETE), and `builtIn` entries every flayr voice applies on its own (an entry of yours for the same term wins).","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Brand id, or `personal`. Default: a bound key's brand, else your active brand."}],"responses":{"200":{"description":"The lexicon","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"pronunciations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string","description":"The written word, e.g. \"Dostal\"."},"sayAs":{"type":"string","description":"How voices say it, e.g. \"Dahss-tuhl\"."},"note":{"type":"string","nullable":true},"alsoRecord":{"type":"boolean"},"spellExact":{"type":"boolean"},"source":{"type":"string","enum":["owner","learned","seed"]},"status":{"type":"string","enum":["active","suggested"],"description":"`suggested` is inert: no voice reads it until accepted."},"suggestedFrom":{"type":"string","nullable":true,"description":"Learned suggestions: what it was learned from (a retake respelling or a misheard transcript)."},"acceptedHearings":{"type":"array","items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass (ASR spelling of the respelling)."},"verified":{"type":"object","nullable":true,"description":"The last passing Verify; null until one passes; cleared when the term or respelling changes.","properties":{"at":{"type":"string","format":"date-time"},"voice":{"type":"string"},"transcript":{"type":"string"}}}}}},"suggested":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string","description":"The written word, e.g. \"Dostal\"."},"sayAs":{"type":"string","description":"How voices say it, e.g. \"Dahss-tuhl\"."},"note":{"type":"string","nullable":true},"alsoRecord":{"type":"boolean"},"spellExact":{"type":"boolean"},"source":{"type":"string","enum":["owner","learned","seed"]},"status":{"type":"string","enum":["active","suggested"],"description":"`suggested` is inert: no voice reads it until accepted."},"suggestedFrom":{"type":"string","nullable":true,"description":"Learned suggestions: what it was learned from (a retake respelling or a misheard transcript)."},"acceptedHearings":{"type":"array","items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass (ASR spelling of the respelling)."},"verified":{"type":"object","nullable":true,"description":"The last passing Verify; null until one passes; cleared when the term or respelling changes.","properties":{"at":{"type":"string","format":"date-time"},"voice":{"type":"string"},"transcript":{"type":"string"}}}}}},"builtIn":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"sayAs":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found, or another brand"},"429":{"description":"Rate or quota limit"}}},"post":{"tags":["API v2"],"summary":"Add a pronunciation","description":"Adds an entry; 422 when the term is already in the scope (use /api/v2/pronunciations/upsert to set it either way). Requires the write scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["term","sayAs"],"additionalProperties":false,"properties":{"term":{"type":"string","maxLength":80},"sayAs":{"type":"string","maxLength":120},"note":{"type":"string"},"alsoRecord":{"type":"boolean","description":"Also tell a human voice actor (default true)."},"spellExact":{"type":"boolean","description":"Read it letter by letter."},"acceptedHearings":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass."},"brandId":{"type":"string","description":"Brand id, or `personal`."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string","description":"The written word, e.g. \"Dostal\"."},"sayAs":{"type":"string","description":"How voices say it, e.g. \"Dahss-tuhl\"."},"note":{"type":"string","nullable":true},"alsoRecord":{"type":"boolean"},"spellExact":{"type":"boolean"},"source":{"type":"string","enum":["owner","learned","seed"]},"status":{"type":"string","enum":["active","suggested"],"description":"`suggested` is inert: no voice reads it until accepted."},"suggestedFrom":{"type":"string","nullable":true,"description":"Learned suggestions: what it was learned from (a retake respelling or a misheard transcript)."},"acceptedHearings":{"type":"array","items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass (ASR spelling of the respelling)."},"verified":{"type":"object","nullable":true,"description":"The last passing Verify; null until one passes; cleared when the term or respelling changes.","properties":{"at":{"type":"string","format":"date-time"},"voice":{"type":"string"},"transcript":{"type":"string"}}}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope"},"404":{"description":"Not found, or another brand"},"422":{"description":"Validation error or duplicate term"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/pronunciations/upsert":{"post":{"tags":["API v2"],"summary":"Set a pronunciation (create or update)","description":"Sets how voices say `term` in the scope: updates the entry with that term (matched trimmed and case-insensitively; a waiting suggestion is accepted) or creates one. Fields left out keep the entry's values. Requires the write scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["term","sayAs"],"additionalProperties":false,"properties":{"term":{"type":"string","maxLength":80},"sayAs":{"type":"string","maxLength":120},"note":{"type":"string"},"alsoRecord":{"type":"boolean","description":"Also tell a human voice actor (default true)."},"spellExact":{"type":"boolean","description":"Read it letter by letter."},"acceptedHearings":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass."},"brandId":{"type":"string","description":"Brand id, or `personal`."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"},"pronunciation":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string","description":"The written word, e.g. \"Dostal\"."},"sayAs":{"type":"string","description":"How voices say it, e.g. \"Dahss-tuhl\"."},"note":{"type":"string","nullable":true},"alsoRecord":{"type":"boolean"},"spellExact":{"type":"boolean"},"source":{"type":"string","enum":["owner","learned","seed"]},"status":{"type":"string","enum":["active","suggested"],"description":"`suggested` is inert: no voice reads it until accepted."},"suggestedFrom":{"type":"string","nullable":true,"description":"Learned suggestions: what it was learned from (a retake respelling or a misheard transcript)."},"acceptedHearings":{"type":"array","items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass (ASR spelling of the respelling)."},"verified":{"type":"object","nullable":true,"description":"The last passing Verify; null until one passes; cleared when the term or respelling changes.","properties":{"at":{"type":"string","format":"date-time"},"voice":{"type":"string"},"transcript":{"type":"string"}}}}}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"},"pronunciation":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string","description":"The written word, e.g. \"Dostal\"."},"sayAs":{"type":"string","description":"How voices say it, e.g. \"Dahss-tuhl\"."},"note":{"type":"string","nullable":true},"alsoRecord":{"type":"boolean"},"spellExact":{"type":"boolean"},"source":{"type":"string","enum":["owner","learned","seed"]},"status":{"type":"string","enum":["active","suggested"],"description":"`suggested` is inert: no voice reads it until accepted."},"suggestedFrom":{"type":"string","nullable":true,"description":"Learned suggestions: what it was learned from (a retake respelling or a misheard transcript)."},"acceptedHearings":{"type":"array","items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass (ASR spelling of the respelling)."},"verified":{"type":"object","nullable":true,"description":"The last passing Verify; null until one passes; cleared when the term or respelling changes.","properties":{"at":{"type":"string","format":"date-time"},"voice":{"type":"string"},"transcript":{"type":"string"}}}}}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope"},"404":{"description":"Not found, or another brand"},"422":{"description":"Validation error"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/pronunciations/{id}":{"patch":{"tags":["API v2"],"summary":"Edit a pronunciation","description":"Only the fields you pass change. PATCHing a learned suggestion accepts it. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Pronunciation id (GET /api/v2/pronunciations)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"term":{"type":"string","maxLength":80},"sayAs":{"type":"string","maxLength":120},"note":{"type":"string"},"alsoRecord":{"type":"boolean","description":"Also tell a human voice actor (default true)."},"spellExact":{"type":"boolean","description":"Read it letter by letter."},"acceptedHearings":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass."},"brandId":{"type":"string","description":"Brand id, or `personal`."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string","description":"The written word, e.g. \"Dostal\"."},"sayAs":{"type":"string","description":"How voices say it, e.g. \"Dahss-tuhl\"."},"note":{"type":"string","nullable":true},"alsoRecord":{"type":"boolean"},"spellExact":{"type":"boolean"},"source":{"type":"string","enum":["owner","learned","seed"]},"status":{"type":"string","enum":["active","suggested"],"description":"`suggested` is inert: no voice reads it until accepted."},"suggestedFrom":{"type":"string","nullable":true,"description":"Learned suggestions: what it was learned from (a retake respelling or a misheard transcript)."},"acceptedHearings":{"type":"array","items":{"type":"string"},"description":"Transcriptions Verify also counts as a pass (ASR spelling of the respelling)."},"verified":{"type":"object","nullable":true,"description":"The last passing Verify; null until one passes; cleared when the term or respelling changes.","properties":{"at":{"type":"string","format":"date-time"},"voice":{"type":"string"},"transcript":{"type":"string"}}}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope"},"404":{"description":"Not found, or another brand"},"422":{"description":"Validation error"},"429":{"description":"Rate or quota limit"}}},"delete":{"tags":["API v2"],"summary":"Delete a pronunciation (or dismiss a suggestion)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Pronunciation id (GET /api/v2/pronunciations)."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Brand id, or `personal`. Default: a bound key's brand, else your active brand."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope"},"404":{"description":"Not found, or another brand"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/pronunciations/{id}/verify":{"get":{"tags":["API v2"],"summary":"Quote a pronunciation Verify","description":"The Ember price of one Verify and the voice and carrier sentence it would use. Nothing runs and nothing is charged.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Pronunciation id (GET /api/v2/pronunciations)."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Brand id, or `personal`. Default: a bound key's brand, else your active brand."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"Gateway TTS model (default Gemini TTS)."},{"name":"voice","in":"query","required":false,"schema":{"type":"string"},"description":"Voice (default Puck)."}],"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"embers":{"type":"integer"},"unit":{"type":"string"},"model":{"type":"string"},"voice":{"type":"string"},"carrierSentence":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found, or another brand"},"422":{"description":"A model or voice that is not offered"},"429":{"description":"Rate or quota limit"}}},"post":{"tags":["API v2"],"summary":"Verify a pronunciation","description":"Speaks a carrier sentence with the entry in the chosen voice (default Gemini Puck), transcribes it, and passes when the transcript has the term or one of its `acceptedHearings`. A pass is stored on the entry. Charges Embers per check (quote it first with GET); never refunded, whether the check fails or speech or transcription fails. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Pronunciation id (GET /api/v2/pronunciations)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"model":{"type":"string"},"voice":{"type":"string"},"brandId":{"type":"string","description":"Brand id, or `personal`."}}}}}},"responses":{"200":{"description":"Checked (passed or not)","content":{"application/json":{"schema":{"type":"object","properties":{"passed":{"type":"boolean"},"matched":{"type":"string","nullable":true,"description":"The term or accepted hearing found in the transcript."},"transcript":{"type":"string"},"carrierSentence":{"type":"string"},"model":{"type":"string"},"voice":{"type":"string"},"asrModel":{"type":"string"},"embersCharged":{"type":"integer"},"stored":{"type":"boolean","description":"A pass is stored on the entry (`verified`)."}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Unauthorized"},"402":{"description":"Not enough Embers"},"403":{"description":"Missing write scope"},"404":{"description":"Not found, or another brand"},"422":{"description":"A model or voice that is not offered"},"429":{"description":"Rate or quota limit"},"502":{"description":"Speech or transcription failed (not refunded)"}}}},"/api/v2/pronunciations/{id}/improve":{"get":{"tags":["API v2"],"summary":"Quote a pronunciation improve round","description":"The Ember price of one charge, how many rounds and samples it covers, and the accents. Nothing runs and nothing is charged.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Pronunciation id (GET /api/v2/pronunciations)."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"embers":{"type":"integer"},"unit":{"type":"string"},"samplesPerRound":{"type":"integer"},"roundsPerCharge":{"type":"integer"},"accentCheck":{"type":"boolean"},"defaultAccent":{"type":"string"},"accents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"locale":{"type":"string"}}}},"note":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found, or another brand"},"429":{"description":"Rate or quota limit"}}},"post":{"tags":["API v2"],"summary":"Run a pronunciation improve round","description":"Makes 3 or more deliberately different samples of the entry (saved respelling, stress and spelling variants, your \"say it like this\" respellings, other voices), each with its script, transcript, word diff and accent check. Send `sessionId` and `feedback` to run another round with all feedback so far. One charge covers `roundsPerCharge` rounds (3 by default); the round after starts a new charge, and `billing.note` says so. Refunded when no sample could be made. Pick a sample with POST /api/v2/voice/improve/sessions/{sessionId}/choose. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Pronunciation id (GET /api/v2/pronunciations)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sessionId":{"type":"string","description":"Continue a session (another round). Absent = start one."},"accent":{"type":"string","enum":["en-US","en-US-texas","en-US-south","en-US-midwest","en-US-newyork","en-CA","en-GB","en-IE","en-AU","es-MX","es-ES","fr-FR","fr-CA"],"description":"Accent and locale (default en-US)."},"model":{"type":"string"},"voice":{"type":"string"},"feedback":{"type":"array","maxItems":30,"description":"Feedback on earlier samples. Another round carries ALL feedback so far.","items":{"type":"object","required":["round","sample"],"properties":{"round":{"type":"integer","minimum":1},"sample":{"type":"integer","minimum":1},"played":{"type":"boolean"},"words":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Words that came out wrong."},"note":{"type":"string","maxLength":300},"sayItLike":{"type":"string","maxLength":80,"description":"\"Say it like this\": a respelling to try next."}}}},"includeAudio":{"type":"boolean","description":"Return each sample as base64 audio. Default true (false through MCP)."},"brandId":{"type":"string","description":"Brand id, or `personal`."}}}}}},"responses":{"200":{"description":"The round","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"round":{"type":"integer"},"term":{"type":"string"},"model":{"type":"string"},"accent":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}}},"samples":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"sayAs":{"type":"string","description":"The respelling this sample used."},"spellExact":{"type":"boolean"},"voice":{"type":"string"},"why":{"type":"string","description":"Why this sample differs: saved, your_respelling, stress, spaced, exact, normalized or other_voice."},"whyLabel":{"type":"string"},"script":{"type":"string","description":"What was spoken."},"transcript":{"type":"string","description":"What speech recognition heard."},"passed":{"type":"boolean"},"matched":{"type":"string","nullable":true},"diff":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"status":{"type":"string"}}}},"accentOk":{"type":"boolean","nullable":true,"description":"null = the accent was not checked."},"accentNote":{"type":"string","nullable":true},"audio":{"type":"object","nullable":true,"properties":{"mediaType":{"type":"string"},"base64":{"type":"string"}}},"error":{"type":"string","nullable":true}}}},"billing":{"type":"object","properties":{"embersCharged":{"type":"integer"},"free":{"type":"boolean","description":"Covered by an earlier charge in this session."},"roundsPerCharge":{"type":"integer"},"coveredThrough":{"type":"integer"},"freeRoundsAfter":{"type":"integer"},"nextRoundCharges":{"type":"boolean"},"note":{"type":"string"}}}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Unauthorized"},"402":{"description":"Not enough Embers"},"403":{"description":"Missing write scope"},"404":{"description":"Not found, or another brand"},"409":{"description":"The session has ended, or a round is still being made"},"422":{"description":"Validation error (unknown accent, voice or field)"},"429":{"description":"Rate or quota limit"},"502":{"description":"No sample could be made (refunded)"}}}},"/api/v2/voice/improve/sessions/{sessionId}/choose":{"post":{"tags":["API v2"],"summary":"Choose an improve sample","description":"The chosen sample's respelling becomes the saved one, marked verified when it passed its transcript check. Ends the session. Free. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"From a round (`sessionId`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["round","sample"],"properties":{"round":{"type":"integer","minimum":1},"sample":{"type":"integer","minimum":1},"feedback":{"type":"array","maxItems":30,"description":"Feedback on earlier samples. Another round carries ALL feedback so far.","items":{"type":"object","required":["round","sample"],"properties":{"round":{"type":"integer","minimum":1},"sample":{"type":"integer","minimum":1},"played":{"type":"boolean"},"words":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Words that came out wrong."},"note":{"type":"string","maxLength":300},"sayItLike":{"type":"string","maxLength":80,"description":"\"Say it like this\": a respelling to try next."}}}},"brandId":{"type":"string","description":"Brand id, or `personal`."}}}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"sayAs":{"type":"string"},"spellExact":{"type":"boolean"},"verified":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope"},"404":{"description":"Not found, or another brand"},"409":{"description":"The session has ended, or the entry was edited"},"422":{"description":"Validation error"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/voice/improve/sessions/{sessionId}/abandon":{"post":{"tags":["API v2"],"summary":"Give up on an improve session","description":"Ends the session. Nothing on the pronunciation changes. Free. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"From a round (`sessionId`)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"feedback":{"type":"array","maxItems":30,"description":"Feedback on earlier samples. Another round carries ALL feedback so far.","items":{"type":"object","required":["round","sample"],"properties":{"round":{"type":"integer","minimum":1},"sample":{"type":"integer","minimum":1},"played":{"type":"boolean"},"words":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Words that came out wrong."},"note":{"type":"string","maxLength":300},"sayItLike":{"type":"string","maxLength":80,"description":"\"Say it like this\": a respelling to try next."}}}},"brandId":{"type":"string","description":"Brand id, or `personal`."}}}}}},"responses":{"200":{"description":"Ended","content":{"application/json":{"schema":{"type":"object","properties":{"ended":{"type":"boolean"},"rounds":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope"},"404":{"description":"Not found, or another brand"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/content/{id}/qa":{"get":{"operationId":"mediaQaGet","summary":"Read cached media QA and gate","tags":["Content"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Findings carry `check`, `severity`, `reason` and `atMs`/`endMs`. Video drafts also get burned-in caption checks read by OCR: `caption_layers`, `cut_mid_caption`, `caption_brand_term`, `burned_text`, `end_cards`, `render_label` and `ocr_not_run`.","responses":{"200":{"description":"Current report, findings with timestamps and shared gate decision."},"404":{"description":"Not found in this key’s scope."}}}},"/api/v2/content/{id}/qa/rerun":{"post":{"operationId":"mediaQaRerun","summary":"Re-run media QA for free","tags":["Content"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires write scope. Queues signals and script transcription under the existing per-minute cap. Keys cannot override.","responses":{"202":{"description":"Queued; poll GET qa."},"422":{"description":"Media not applicable."}}}},"/api/v2/analytics/experiments":{"get":{"tags":["API v2"],"summary":"Compare posts by a label key (A/B by label)","description":"Every labelled post in scope split by the values of one label key — e.g. key=cut compares cut:opus vs cut:claude vs cut:raw. Metrics come from 48h / 7-day snapshots so posts are compared at the same age. Descriptive only: n per group is small, so nothing is statistically tested; read medians with their n and min/max. Needs the analytics plan feature.","security":[{"bearerAuth":[]}],"parameters":[{"name":"key","in":"query","required":false,"schema":{"type":"string","default":"cut"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id, or \"all\" (default: every profile you can see). A brand-bound key is always its own brand."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["48h","7d","latest"],"default":"48h"}},{"name":"metric","in":"query","required":false,"schema":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","averageViewPercentage"],"default":"impressions"},"description":"Which metric \"leading\" ranks by."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"]},"description":"csv: one row per post with every window's metrics, then its human review: reviewStatus, reviewedBy, reviewedAt, qaPassed, qa_credit, qa_caption, qa_platforms, qa_media, qaCheckedBy, qaCheckedAt, mediaFix, mediaFixBy, mediaFixAt."},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["posts"]}}],"responses":{"200":{"description":"Comparison (or CSV)","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"window":{"type":"string","enum":["h48","d7","d30","latest"]},"primaryMetric":{"type":"string"},"leading":{"type":"object","nullable":true,"properties":{"value":{"type":"string"},"median":{"type":"number"},"n":{"type":"integer"}}},"groups":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","description":"A value of the key; \"(none)\" for posts without one."},"posts":{"type":"integer"},"metrics":{"type":"object","description":"Per window (h48 = 48h snapshot, d7 = 7-day snapshot, latest), per metric (impressions, views, engagement, engagementRate, clicks, averageViewPercentage): n / median / mean / min / max.","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"n":{"type":"integer"},"median":{"type":"number","nullable":true},"mean":{"type":"number","nullable":true},"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true}}}}},"platforms":{"type":"object","additionalProperties":{"type":"object","properties":{"posts":{"type":"integer"},"metrics":{"type":"object","description":"Per window (h48 = 48h snapshot, d7 = 7-day snapshot, latest), per metric (impressions, views, engagement, engagementRate, clicks, averageViewPercentage): n / median / mean / min / max.","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"n":{"type":"integer"},"median":{"type":"number","nullable":true},"mean":{"type":"number","nullable":true},"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true}}}}}}}}}}},"pairs":{"type":"array","items":{"type":"object","properties":{"ab":{"type":"string"},"leader":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object"}}}}},"totalPosts":{"type":"integer"},"truncated":{"type":"boolean","description":"More than 300 labelled posts: only the newest 300 are compared."},"note":{"type":"string"},"posts":{"type":"array","items":{"type":"object"},"description":"Only with include=posts. FFE-1204: byWindow / byPlatform.<platform>.<window>.breakdown carries the video watch fields (avgWatchTimeMs, avgViewPercentage 0-100, completionRate, skipRate) where the platform reports them; an absent field means not reported / not available on that platform, never zero. Each post carries `review` (null = not reviewed): { status, reviewedBy, reviewedAt, checklist: { credit, caption, platforms, media: \"ok\" | \"flagged\" }, qaPassed, checkedBy, checkedAt, mediaFix }."}}}}}},"402":{"description":"Analytics not on this plan (Pro+)"},"403":{"description":"Another brand for a brand-bound key"},"404":{"description":"Unknown brand"},"422":{"description":"Invalid key / window / metric"}}}},"/api/v2/experiments":{"get":{"tags":["API v2"],"summary":"List experiments","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id, or \"all\" (default: every profile you can see). A brand-bound key is always its own brand."},{"name":"allBrands","in":"query","required":false,"schema":{"type":"boolean"},"description":"true: every brand of the organizations you own or administer, plus your personal brands. Refused (403) for a plain member and for a brand-bound key."}],"responses":{"200":{"description":"Experiments","content":{"application/json":{"schema":{"type":"object","properties":{"experiments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hypothesis":{"type":"string","nullable":true},"compareKey":{"type":"string","description":"The label key the arms are split by (default \"variant\")."},"variants":{"type":"array","items":{"type":"string"}},"label":{"type":"string","description":"Tag content with this label to add it: \"experiment:<id>\"."},"brandId":{"type":"string"},"startAt":{"type":"string","format":"date-time","nullable":true},"endAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["draft","running","done"]},"primaryMetric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","averageViewPercentage"]},"notes":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"403":{"description":"allBrands as a plain member or with a brand-bound key"}}},"post":{"tags":["API v2"],"summary":"Create an experiment","description":"Then tag content with its `label` (experiment:<id>) plus <compareKey>:<variant> via PATCH /api/v2/content/{id} `labels`. Requires the write scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":120},"hypothesis":{"type":"string","maxLength":2000},"compareKey":{"type":"string"},"variants":{"type":"array","maxItems":12,"items":{"type":"string"}},"startAt":{"type":"string","format":"date-time","nullable":true},"endAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["draft","running","done"]},"primaryMetric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","averageViewPercentage"]},"notes":{"type":"string","maxLength":2000},"brandId":{"type":"string","description":"A brand id, or \"personal\" (default)."}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hypothesis":{"type":"string","nullable":true},"compareKey":{"type":"string","description":"The label key the arms are split by (default \"variant\")."},"variants":{"type":"array","items":{"type":"string"}},"label":{"type":"string","description":"Tag content with this label to add it: \"experiment:<id>\"."},"brandId":{"type":"string"},"startAt":{"type":"string","format":"date-time","nullable":true},"endAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["draft","running","done"]},"primaryMetric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","averageViewPercentage"]},"notes":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Missing write scope"},"422":{"description":"Validation error"}}}},"/api/v2/experiments/{id}":{"get":{"tags":["API v2"],"summary":"Get an experiment","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Experiment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hypothesis":{"type":"string","nullable":true},"compareKey":{"type":"string","description":"The label key the arms are split by (default \"variant\")."},"variants":{"type":"array","items":{"type":"string"}},"label":{"type":"string","description":"Tag content with this label to add it: \"experiment:<id>\"."},"brandId":{"type":"string"},"startAt":{"type":"string","format":"date-time","nullable":true},"endAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["draft","running","done"]},"primaryMetric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","averageViewPercentage"]},"notes":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Not found"}}},"patch":{"tags":["API v2"],"summary":"Update an experiment","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":120},"hypothesis":{"type":"string","maxLength":2000},"compareKey":{"type":"string"},"variants":{"type":"array","maxItems":12,"items":{"type":"string"}},"startAt":{"type":"string","format":"date-time","nullable":true},"endAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["draft","running","done"]},"primaryMetric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","averageViewPercentage"]},"notes":{"type":"string","maxLength":2000}},"minProperties":1}}}},"responses":{"200":{"description":"Experiment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hypothesis":{"type":"string","nullable":true},"compareKey":{"type":"string","description":"The label key the arms are split by (default \"variant\")."},"variants":{"type":"array","items":{"type":"string"}},"label":{"type":"string","description":"Tag content with this label to add it: \"experiment:<id>\"."},"brandId":{"type":"string"},"startAt":{"type":"string","format":"date-time","nullable":true},"endAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["draft","running","done"]},"primaryMetric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","averageViewPercentage"]},"notes":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["API v2"],"summary":"Delete an experiment (content keeps its label)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ deleted }"},"404":{"description":"Not found"}}}},"/api/v2/experiments/{id}/results":{"get":{"tags":["API v2"],"summary":"Experiment results","description":"The experiment's posts (label experiment:<id>, published between startAt and endAt) split by its compareKey, planned variants first, with the leading variant by its primaryMetric and n per arm.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["48h","7d","latest"],"default":"48h"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"]},"description":"csv: one row per post with every window's metrics, then its human review: reviewStatus, reviewedBy, reviewedAt, qaPassed, qa_credit, qa_caption, qa_platforms, qa_media, qaCheckedBy, qaCheckedAt, mediaFix, mediaFixBy, mediaFixAt."},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["posts"]}},{"name":"align","in":"query","required":false,"schema":{"type":"string","enum":["calendar","armDay"],"default":"calendar"},"description":"calendar: by publish date. armDay: arms lined up from their first post."}],"responses":{"200":{"description":"{ experiment, results, overlay }","content":{"application/json":{"schema":{"type":"object","properties":{"experiment":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hypothesis":{"type":"string","nullable":true},"compareKey":{"type":"string","description":"The label key the arms are split by (default \"variant\")."},"variants":{"type":"array","items":{"type":"string"}},"label":{"type":"string","description":"Tag content with this label to add it: \"experiment:<id>\"."},"brandId":{"type":"string"},"startAt":{"type":"string","format":"date-time","nullable":true},"endAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["draft","running","done"]},"primaryMetric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","averageViewPercentage"]},"notes":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"results":{"type":"object","properties":{"key":{"type":"string"},"window":{"type":"string","enum":["h48","d7","d30","latest"]},"primaryMetric":{"type":"string"},"leading":{"type":"object","nullable":true,"properties":{"value":{"type":"string"},"median":{"type":"number"},"n":{"type":"integer"}}},"groups":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","description":"A value of the key; \"(none)\" for posts without one."},"posts":{"type":"integer"},"metrics":{"type":"object","description":"Per window (h48 = 48h snapshot, d7 = 7-day snapshot, latest), per metric (impressions, views, engagement, engagementRate, clicks, averageViewPercentage): n / median / mean / min / max.","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"n":{"type":"integer"},"median":{"type":"number","nullable":true},"mean":{"type":"number","nullable":true},"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true}}}}},"platforms":{"type":"object","additionalProperties":{"type":"object","properties":{"posts":{"type":"integer"},"metrics":{"type":"object","description":"Per window (h48 = 48h snapshot, d7 = 7-day snapshot, latest), per metric (impressions, views, engagement, engagementRate, clicks, averageViewPercentage): n / median / mean / min / max.","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"n":{"type":"integer"},"median":{"type":"number","nullable":true},"mean":{"type":"number","nullable":true},"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true}}}}}}}}}}},"pairs":{"type":"array","items":{"type":"object","properties":{"ab":{"type":"string"},"leader":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object"}}}}},"totalPosts":{"type":"integer"},"truncated":{"type":"boolean","description":"More than 300 labelled posts: only the newest 300 are compared."},"note":{"type":"string"},"posts":{"type":"array","items":{"type":"object"},"description":"Only with include=posts. FFE-1204: byWindow / byPlatform.<platform>.<window>.breakdown carries the video watch fields (avgWatchTimeMs, avgViewPercentage 0-100, completionRate, skipRate) where the platform reports them; an absent field means not reported / not available on that platform, never zero. Each post carries `review` (null = not reviewed): { status, reviewedBy, reviewedAt, checklist: { credit, caption, platforms, media: \"ok\" | \"flagged\" }, qaPassed, checkedBy, checkedAt, mediaFix }."}}},"overlay":{"type":"object","description":"One line per arm: the primary metric to date over the arm's posts. A null value is \"not reported\", never 0.","properties":{"metric":{"type":"string"},"window":{"type":"string"},"unit":{"type":"string","enum":["rate","percent","count"]},"align":{"type":"string","enum":["calendar","armDay"]},"axis":{"type":"array","items":{"type":"string"},"description":"ISO dates, or arm days 1..N"},"lines":{"type":"array","items":{"type":"object","properties":{"arm":{"type":"string"},"posts":{"type":"integer"},"values":{"type":"array","items":{"type":"number","nullable":true}},"span":{"type":"object","nullable":true,"properties":{"start":{"type":"integer"},"end":{"type":"integer"},"ended":{"type":"boolean"}}}}}}}}}}}}},"404":{"description":"Not found"},"422":{"description":"Bad window or align"}}}},"/api/v2/experiments/{id}/readout":{"get":{"tags":["API v2"],"summary":"Experiment readout (n per arm, 90% interval, verdict)","description":"ai-06: counts only published posts with a metric snapshot at the window; cancelled, failed, not-yet-published and not-yet-reported posts are reported per arm, never counted. Compares pooled reach-ER: the leader against the runner-up, with a seeded bootstrap 90% CI and a Mann-Whitney p. Needs at least 5 counted posts per arm and 7 days running before it gives a verdict. Needs the analytics plan feature.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["48h","7d","30d","latest"],"default":"48h"}}],"responses":{"200":{"description":"Readout","content":{"application/json":{"schema":{"type":"object","required":["experimentId","verdict","window","metric","arms","copy"],"properties":{"experimentId":{"type":"string"},"verdict":{"type":"string","enum":["not_enough_data","no_clear_winner","likely_winner"],"description":"not_enough_data: an arm is under minPostsPerArm counted posts, fewer than two arms have data, or the experiment has run under minDays. no_clear_winner: the 90% interval crosses 0 or p ≥ 0.1. likely_winner: neither. Never \"proven\": samples are small."},"window":{"type":"string","enum":["h48","d7","latest","d30"]},"metric":{"type":"string","enum":["reach_er","averageViewPercentage"],"description":"Pooled reach engagement rate, or average percentage watched when selected as primaryMetric. Watch readouts exclude unavailable platforms and weight by reported watch-time views; arm.er is the pooled fraction watched and intervals are percentage points. Replays may exceed 100%."},"arms":{"type":"array","items":{"type":"object","properties":{"arm":{"type":"string","description":"A value of the compareKey; planned variants first."},"posts":{"type":"integer","description":"Counted posts: published, with a snapshot and reach at the window."},"excluded":{"type":"object","properties":{"cancelled":{"type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer","description":"Not published yet."},"notReported":{"type":"integer","description":"Published, no snapshot (or no reach) at this window yet."}}},"reach":{"type":"number","nullable":true,"description":"null = not reported (no counted posts), never 0."},"engagement":{"type":"number","nullable":true},"er":{"type":"number","nullable":true,"description":"Pooled reach-ER as a fraction (0.024 = 2.4%); null = not reported."}}}},"unassigned":{"type":"integer","description":"Posts with no value, or several values, of the compareKey."},"daysRunning":{"type":"number"},"needsMore":{"type":"array","items":{"type":"object","properties":{"arm":{"type":"string"},"posts":{"type":"integer"}}},"description":"not_enough_data: counted posts each short arm still needs."},"needsDays":{"type":"integer","description":"not_enough_data: days still needed to reach minDays."},"needsArms":{"type":"boolean","description":"not_enough_data: fewer than two arms have counted posts."},"leader":{"type":"string","description":"no_clear_winner: ahead on the point estimate only."},"arm":{"type":"string","description":"likely_winner: the arm likely ahead."},"versus":{"type":"string","description":"The runner-up the leader is tested against."},"liftPts":{"type":"number","description":"Pooled-ER difference, leader − runner-up, in percentage points."},"ci90":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"90% bootstrap interval of the pooled-ER difference (leader − runner-up), in percentage points."},"pValue":{"type":"number","description":"Two-sided Mann-Whitney U on per-post ER (exact when both arms ≤ 8)."},"probAhead":{"type":"number","description":"Share of 5,000 bootstrap resamples (seeded, deterministic) where the leader is ahead."},"config":{"type":"object","properties":{"minPostsPerArm":{"type":"integer"},"minDays":{"type":"integer"},"iters":{"type":"integer"},"seed":{"type":"integer"}}},"copy":{"type":"object","properties":{"headline":{"type":"string"},"detail":{"type":"string"}},"description":"Plain-language readout; hedged (\"likely\"), never \"proven\"."},"truncated":{"type":"boolean","description":"More than 300 labelled posts: only the newest 300 are read."}}}}}},"402":{"description":"Analytics not on this plan (Pro+)"},"404":{"description":"Not found (or another brand than a brand-bound key)"},"422":{"description":"Invalid window"}}}},"/api/v2/experiments/{id}/rounds":{"get":{"tags":["API v2"],"summary":"Version test rounds","description":"The rounds of a version test (\"Test versions\" in the app): each closed round's frozen snapshot, the open round's live snapshot, the winner and any repeat plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Rounds","content":{"application/json":{"schema":{"type":"object","properties":{"experimentId":{"type":"string"},"roundsPlanned":{"type":"integer"},"rounds":{"type":"array","items":{"type":"object","properties":{"n":{"type":"integer"},"arms":{"type":"array","items":{"type":"string"}},"startAt":{"type":"number"},"endAt":{"type":"number"},"status":{"type":"string","enum":["open","closed"]},"readout":{"type":"object","description":"A round snapshot: per-version metric plus the shared experiment readout (see GET /api/v2/experiments/{id}/readout).","properties":{"window":{"type":"string"},"metric":{"type":"string"},"takenAt":{"type":"number"},"arms":{"type":"array","items":{"type":"object","properties":{"arm":{"type":"string","example":"v2"},"posts":{"type":"integer","description":"Counted posts (published, measured at the window)."},"value":{"type":"number","nullable":true,"description":"Mean of the loop metric per counted post; null = not reported."},"reach":{"type":"number","nullable":true,"description":"Summed reach; null = not reported."}}}},"armPostIds":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"readout":{"type":"object"}}},"keptArms":{"type":"array","items":{"type":"string"}},"winnerArm":{"type":"string"},"decidedBy":{"type":"string","enum":["readout","user"]},"closedAt":{"type":"number"}}}},"live":{"type":"object","description":"A round snapshot: per-version metric plus the shared experiment readout (see GET /api/v2/experiments/{id}/readout).","properties":{"window":{"type":"string"},"metric":{"type":"string"},"takenAt":{"type":"number"},"arms":{"type":"array","items":{"type":"object","properties":{"arm":{"type":"string","example":"v2"},"posts":{"type":"integer","description":"Counted posts (published, measured at the window)."},"value":{"type":"number","nullable":true,"description":"Mean of the loop metric per counted post; null = not reported."},"reach":{"type":"number","nullable":true,"description":"Summed reach; null = not reported."}}}},"armPostIds":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"readout":{"type":"object"}},"nullable":true},"winnerArm":{"type":"string","nullable":true},"repeatPlan":{"type":"object","properties":{"arm":{"type":"string"},"slots":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"slotAt":{"type":"number"}}}},"status":{"type":"string","enum":["proposed","confirmed","dismissed"]},"proposedAt":{"type":"number"}},"nullable":true},"config":{"type":"object"},"truncated":{"type":"boolean"}}}}}},"402":{"description":"Analytics not on this plan (Pro+)"},"404":{"description":"Not found, not a version test, or another brand than a brand-bound key"}}},"post":{"tags":["API v2"],"summary":"Start the next round","description":"Files the round's versions into the approval queue (pending approval), spaced so no two versions share a slot, with UTM-tagged links. Round 1 tests every version; later rounds re-test the versions the last round kept. Nothing is published or scheduled until approved. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platforms"],"properties":{"platforms":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"example":["instagram","tiktok"]},"startAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"number"}],"description":"First slot; default now."}}}}}},"responses":{"201":{"description":"{ round, filed: [{ arm, contentId, slotAt, approvalId }], approval: \"pending\" }"},"402":{"description":"Analytics not on this plan (Pro+)"},"404":{"description":"Not found, not a version test, or another brand than a brand-bound key"},"422":{"description":"Validation error, a round is open, or the test is decided"}}}},"/api/v2/experiments/{id}/close-round":{"post":{"tags":["API v2"],"summary":"Close the open round","description":"Freezes the round snapshot and keeps the top versions. A winner is recorded only when the readout says likely_winner or `pick` names one of the round's versions. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pick":{"type":"string","example":"v2"}}}}}},"responses":{"200":{"description":"{ round, winner }"},"402":{"description":"Analytics not on this plan (Pro+)"},"404":{"description":"Not found, not a version test, or another brand than a brand-bound key"},"422":{"description":"No open round, or pick is not a version of this round"}}}},"/api/v2/experiments/{id}/repeat-winner":{"post":{"tags":["API v2"],"summary":"Propose repeating the winner","description":"Proposal only: the slots the winning version would be repeated in (default 3 over 2 weeks; platforms it won on first, then untested ones). No content is written and nothing is booked; confirming happens in the app and still goes through the approval queue. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"platforms":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"example":["instagram","tiktok"]},"startAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"number"}],"description":"First slot; default now."}}}}}},"responses":{"200":{"description":"Proposal","content":{"application/json":{"schema":{"type":"object","properties":{"arm":{"type":"string"},"slots":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"slotAt":{"type":"number"}}}},"status":{"type":"string","enum":["proposed","confirmed","dismissed"]},"proposedAt":{"type":"number"}}}}}},"402":{"description":"Analytics not on this plan (Pro+)"},"404":{"description":"Not found, not a version test, or another brand than a brand-bound key"},"422":{"description":"No winner yet"}}}},"/api/v2/labels/taxonomy":{"get":{"tags":["API v2"],"summary":"Get the tag preset","description":"The label keys and values this brand tags with. With nothing saved, the tagging taxonomy v1 default (`isDefault: true`). A preset is a suggestion list: any valid label is still accepted on content and posts.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; omitted = the brand active in the dashboard. A brand-bound key is always pinned to its brand; any other value is 403."}],"responses":{"200":{"description":"Tag preset","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"brandName":{"type":"string"},"brandValue":{"type":"string","description":"The `brand:` label value for this brand."},"isDefault":{"type":"boolean","description":"Nothing saved yet: the tagging taxonomy v1 default."},"canEdit":{"type":"boolean","description":"The key owner may change it (brand owner/admin, or the Personal space owner)."},"taxonomyVersion":{"type":"integer","minimum":1,"default":1},"keys":{"type":"array","maxItems":20,"items":{"type":"object","required":["key"],"properties":{"key":{"type":"string","maxLength":32,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"A label key. `area`, `experiment` and `campaign` are reserved and refused."},"multi":{"type":"boolean","default":false,"description":"An item can carry more than one value."},"required":{"type":"boolean","default":false,"description":"Should be on every new piece. A reminder in the editor (\"missing: line\"), never a block."},"values":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":80},"description":"Values offered first, in order. Empty = any value. Normalized like labels (lowercase, spaces → \"-\")."},"groups":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Grouped keys (format): group name → values; every value must be in `values`."},"legacyValues":{"type":"array","items":{"type":"string"},"description":"Older values kept on existing items; shown, not offered."}}}},"defaultLine":{"type":"string","nullable":true,"description":"The `line:` used when nothing else matches; null = none."},"autoTag":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"Auto-tag new content (adds labels only; never removes or changes one a person set)."},"llm":{"type":"boolean","default":true,"description":"Let AI suggest the line and hook from the caption."}}}}}}}},"403":{"description":"Another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}},"put":{"tags":["API v2"],"summary":"Replace the tag preset","description":"Replaces the whole preset for `brandId`. Requires the write scope, and the key owner must be an owner or admin of the brand (or own the Personal space). Never changes any existing label.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keys"],"properties":{"taxonomyVersion":{"type":"integer","minimum":1,"default":1},"keys":{"type":"array","maxItems":20,"items":{"type":"object","required":["key"],"properties":{"key":{"type":"string","maxLength":32,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"A label key. `area`, `experiment` and `campaign` are reserved and refused."},"multi":{"type":"boolean","default":false,"description":"An item can carry more than one value."},"required":{"type":"boolean","default":false,"description":"Should be on every new piece. A reminder in the editor (\"missing: line\"), never a block."},"values":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":80},"description":"Values offered first, in order. Empty = any value. Normalized like labels (lowercase, spaces → \"-\")."},"groups":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Grouped keys (format): group name → values; every value must be in `values`."},"legacyValues":{"type":"array","items":{"type":"string"},"description":"Older values kept on existing items; shown, not offered."}}}},"defaultLine":{"type":"string","nullable":true,"description":"The `line:` used when nothing else matches; null = none."},"autoTag":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"Auto-tag new content (adds labels only; never removes or changes one a person set)."},"llm":{"type":"boolean","default":true,"description":"Let AI suggest the line and hook from the caption."}}},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"brandName":{"type":"string"},"brandValue":{"type":"string","description":"The `brand:` label value for this brand."},"isDefault":{"type":"boolean","description":"Nothing saved yet: the tagging taxonomy v1 default."},"canEdit":{"type":"boolean","description":"The key owner may change it (brand owner/admin, or the Personal space owner)."},"taxonomyVersion":{"type":"integer","minimum":1,"default":1},"keys":{"type":"array","maxItems":20,"items":{"type":"object","required":["key"],"properties":{"key":{"type":"string","maxLength":32,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"A label key. `area`, `experiment` and `campaign` are reserved and refused."},"multi":{"type":"boolean","default":false,"description":"An item can carry more than one value."},"required":{"type":"boolean","default":false,"description":"Should be on every new piece. A reminder in the editor (\"missing: line\"), never a block."},"values":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":80},"description":"Values offered first, in order. Empty = any value. Normalized like labels (lowercase, spaces → \"-\")."},"groups":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Grouped keys (format): group name → values; every value must be in `values`."},"legacyValues":{"type":"array","items":{"type":"string"},"description":"Older values kept on existing items; shown, not offered."}}}},"defaultLine":{"type":"string","nullable":true,"description":"The `line:` used when nothing else matches; null = none."},"autoTag":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"Auto-tag new content (adds labels only; never removes or changes one a person set)."},"llm":{"type":"boolean","default":true,"description":"Let AI suggest the line and hook from the caption."}}}}}}}},"403":{"description":"Missing write scope, another brand for a brand-bound key, or not an owner/admin of the brand"},"404":{"description":"Unknown brand"},"422":{"description":"Invalid or reserved key, invalid value, unknown field (the message names it)"}}}},"/api/v2/content/suggest-tags":{"post":{"tags":["API v2"],"summary":"Suggest hashtags and @mentions per platform","description":"Suggestions only: nothing is added to any caption. Hashtags come from the brand profile's hashtag sets; mentions from the brand's mention contacts, written per network. The brand is the key's brand, or for an account-wide key the brand active in the dashboard. Read scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platforms"],"properties":{"platforms":{"type":"array","minItems":1,"items":{"type":"string","enum":["instagram","tiktok","youtube","youtube_shorts","linkedin","twitter","threads","bluesky","facebook"]}},"text":{"type":"string","maxLength":10000,"description":"The caption so far; tags and mentions already in it are not suggested again."}}}}}},"responses":{"200":{"description":"Suggestions, one entry per distinct platform","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"mentionStyle":{"type":"string","enum":["handle","linkedin_urn"],"description":"`handle` = `@handle`; `linkedin_urn` = `@[Name](urn:li:organization:…)`."},"hashtagCount":{"type":"integer","description":"Hashtags already in `text`."},"maxHashtags":{"type":"integer","nullable":true,"description":"The platform's hard cap (publish trims extra hashtags), or null when it has none."},"suggestedMaxHashtags":{"type":"integer","nullable":true,"description":"The cap suggestions stay within: the hard cap, else the platform's recommendation."},"hashtags":{"type":"array","description":"From the brand profile's hashtag sets, deduplicated, skipping tags already in `text`, within the room left under the cap.","items":{"type":"object","properties":{"tag":{"type":"string"},"set":{"type":"string","description":"The hashtag set it came from."}}}},"mentions":{"type":"array","description":"Mention contacts with an account on this platform. No account = not listed (a mention of them posts as plain text).","items":{"type":"object","properties":{"contactId":{"type":"string"},"label":{"type":"string"},"text":{"type":"string","description":"Exactly what the network receives."},"inCaption":{"type":"boolean","description":"The contact's name already appears in `text`."}}}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"422":{"description":"Unknown platform, unknown field or invalid text (the message names it)"}}}},"/api/v2/content/labels":{"post":{"tags":["API v2"],"summary":"Add or remove labels on many items","description":"Each item's labels become (labels − remove) + add, written like PATCH /api/v2/content/{id} `labels` (posts made from it are re-labelled too). Up to 100 ids. Labels are metadata: published items are fine. Same access per item as GET; a brand-bound key only reaches its own brand. Requires the write (or admin) scope. Items fail on their own (`ok: false` with a status); the rest are still written. Removing `source:ai-generated` does not turn the post's AI label off: with no explicit toggle it follows how the media was made. For real footage also PATCH `aiGenerated: false`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"additionalProperties":false,"properties":{"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"Content ids (GET /api/v2/content)."},"add":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"},"description":"Labels to add. Normalized \"key:value\" labels (keys and values are lower-cased, spaces become \"-\"). Linked keys: campaign:<media campaign id>, experiment:<experiment id> (+ variant:<name> or the experiment's compareKey), type:<post type> (short, long-form, carousel, image, text, reel, story, poem, timelapse…). Free keys work too: cut:opus, lane:tech, parent:pantheon-part-1, ab:<pair id> (an A/B pair). Labels are copied onto every post made from the draft, and compared in GET /api/v2/analytics/experiments."},"remove":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"},"description":"Labels to remove. Not also in `add`."}}}}}},"responses":{"200":{"description":"Per-item results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","required":["id","ok"],"properties":{"id":{"type":"string"},"ok":{"type":"boolean"},"labels":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"},"description":"ok: the item's labels after the edit."},"aiGenerated":{"type":"boolean","nullable":true,"description":"ok: the item's AI label toggle (null = automatic). Change it with PATCH /api/v2/content/{id} `aiGenerated`."},"warning":{"type":"string","description":"ok, when `remove` took `source:ai-generated` off an item whose AI label is automatic and whose media flayr made: \"The AI label follows how this was made. Set aiGenerated=false if this is real footage.\""},"status":{"type":"integer","description":"Not ok: 403 not allowed to edit it, 404 not found or another brand, 422 over the label limit."},"error":{"type":"string"}}}},"updated":{"type":"integer"},"failed":{"type":"integer"}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope"},"422":{"description":"Validation error: no ids, more than 100 ids, an invalid label, nothing to add or remove, or a label in both lists"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/content/{id}/archive":{"post":{"tags":["API v2"],"summary":"Soft-archive a draft","description":"Requires write (or admin) scope. Archives draft, failed or completed generation content with no posting queue, post or approval history. Ready, staged, scheduled and published content is refused. Preserves the content, media and original status for Restore in the Library Archive view. Repeating the request returns changed: false. The owner may archive their own draft; another member needs admin/owner in the same organization. Brand-bound keys can only archive their own brand’s content, including on retries.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Content id from GET /api/v2/content."}],"responses":{"200":{"description":"Archived, or already archived","content":{"application/json":{"schema":{"type":"object","required":["id","status","changed"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["archived"]},"changed":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Missing write scope or insufficient organization role"},"404":{"description":"Malformed id, not found, or outside the caller’s ownership/brand"},"409":{"description":"Not an uncommitted draft, or has posting/approval history; nothing changed"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/content/auto-tag":{"post":{"tags":["API v2"],"summary":"Re-run auto-tag (preview, then apply)","description":"Re-runs auto-tag on a selection (`contentIds`, at most 100) or a whole brand (`clientProfileId`, 100 rows per call with `cursor`). `dryRun: true` returns the labels it would add and writes nothing; it needs the read scope. `includeLlm: true` also asks AI for the line and hook (write scope; real model calls, at most 100 per call). `dryRun: false` needs the write scope and the `previewHash` of a dry run. Send the preview's `items` back, or omit them to re-run the same preview (not allowed with `includeLlm`); a preview that no longer matches is a 409. Add-only and idempotent. Labels set by a person win. Label changes never re-sync scheduled posts to the social network.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dryRun"],"additionalProperties":false,"properties":{"contentIds":{"type":"array","maxItems":100,"items":{"type":"string"}},"clientProfileId":{"type":"string","description":"A brand id (GET /api/v2/brands). A brand-bound key is pinned to its brand; another brand is 403."},"dryRun":{"type":"boolean"},"includeLlm":{"type":"boolean","default":false},"cursor":{"type":"string","nullable":true},"previewHash":{"type":"string"},"items":{"type":"array","maxItems":100,"items":{"type":"object","required":["contentId","add"],"properties":{"contentId":{"type":"string"},"add":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"Labels to add. Only `brand`, `source`, `format`, `line` and `hook` keys."}}}}}}}}},"responses":{"200":{"description":"The preview (`dryRun: true`) or the apply result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"contentId":{"type":"string"},"title":{"type":"string","description":"The first 80 characters of the title or caption."},"add":{"type":"array","items":{"type":"string"},"description":"Labels the apply would add. Never removes or changes a label."},"llmPending":{"type":"boolean","description":"The LLM step could still add a `line:` or `hook:` (preview with `includeLlm: true`)."},"dropped":{"type":"array","items":{"type":"string"},"description":"Labels left out to stay within 30 labels per item."},"skippedBecause":{"type":"string","enum":["not_found","no_write_access","archived","outside_brand","auto_tag_off","changed_since_preview","nothing_to_add","max_labels"]}}}},"previewHash":{"type":"string","description":"Send back with `dryRun: false` to apply exactly this preview."},"total":{"type":"integer","description":"Labels the apply would add, across rows."},"items":{"type":"array","items":{"type":"object","required":["contentId","add"],"properties":{"contentId":{"type":"string"},"add":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"Labels to add. Only `brand`, `source`, `format`, `line` and `hook` keys."}}},"description":"The rows with adds, ready to send back."},"nextCursor":{"type":"string","nullable":true,"description":"For a brand-wide run: the cursor of the next 100 rows."},"isDone":{"type":"boolean","description":"The last page of the brand."}}},{"type":"object","properties":{"updated":{"type":"integer","description":"Items that gained at least one label. A second run of the same preview updates 0."},"skipped":{"type":"array","items":{"type":"object","properties":{"contentId":{"type":"string"},"reason":{"type":"string","enum":["not_found","no_write_access","archived","outside_brand","auto_tag_off","changed_since_preview","nothing_to_add","max_labels"]}}},"description":"`changed_since_preview`: a person set that label since the preview, and their label wins."},"dropped":{"type":"array","items":{"type":"object","properties":{"contentId":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}}}}}}}]}}}},"400":{"description":"Invalid JSON"},"403":{"description":"Missing scope, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"},"409":{"description":"The preview no longer matches; run the dry run again"},"422":{"description":"Invalid body"}}}},"/api/v2/text-templates":{"get":{"tags":["API v2"],"summary":"List formats (text templates)","description":"Reusable text shapes per brand: sections, length targets, hook patterns, CTA slots and guardrails.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands), \"personal\", or \"all\" (default: everything the key owner can see). A brand-bound key is always pinned to its brand; any other value is 403."},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Formats","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"name":{"type":"string","maxLength":120},"format":{"type":"string","enum":["post","article","carousel_script","meme","thread"]},"platform":{"type":"string","nullable":true,"description":"e.g. \"linkedin\"; null = any platform."},"useFor":{"type":"string","nullable":true,"maxLength":300,"description":"One line: when to pick this format."},"length":{"type":"object","required":["unit","min","max"],"properties":{"unit":{"type":"string","enum":["words","chars","slides"]},"min":{"type":"integer","minimum":0},"max":{"type":"integer","minimum":1},"perSlideMaxWords":{"type":"integer","description":"carousel_script / thread: words allowed per slide or post."},"titleMaxWords":{"type":"integer","description":"carousel_script: words allowed in the title (first line of slide 1)."},"captionWords":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"description":"carousel_script: the caption that goes with the slides."}}},"sections":{"type":"array","maxItems":20,"description":"In order. \"Start from a format\" writes one `[you fill: Label — guidance]` placeholder per section.","items":{"type":"object","required":["label"],"properties":{"key":{"type":"string","description":"Derived from the label when omitted."},"label":{"type":"string","maxLength":80},"guidance":{"type":"string","maxLength":1000},"required":{"type":"boolean","default":true},"minLines":{"type":"integer"},"maxLines":{"type":"integer"}}}},"hookPatterns":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300},"description":"\"[slot]\" placeholders are kept as written."},"ctaSlots":{"type":"array","maxItems":10,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"text":{"type":"string"},"placement":{"type":"string","enum":["body","first_comment","none"],"default":"body"}}}},"guardrails":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":500}},"maxHashtags":{"type":"integer","nullable":true,"minimum":0,"maximum":30},"defaultLabels":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"\"key:value\" labels every draft started from this format gets (plus the format's own `label`)."},"example":{"type":"string","nullable":true,"maxLength":20000},"source":{"type":"string","nullable":true,"maxLength":200,"description":"Where the shape came from, e.g. an import path."},"label":{"type":"string","description":"template:<id> — every draft started from this format carries it."},"archived":{"type":"boolean"},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"403":{"description":"Another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}},"post":{"tags":["API v2"],"summary":"Create a format","description":"Created in `brandId` (a brand, or \"personal\" — the default for account-wide keys; a brand-bound key always creates in its brand). Requires the write scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","format","length"],"properties":{"name":{"type":"string","maxLength":120},"format":{"type":"string","enum":["post","article","carousel_script","meme","thread"]},"platform":{"type":"string","nullable":true,"description":"e.g. \"linkedin\"; null = any platform."},"useFor":{"type":"string","nullable":true,"maxLength":300,"description":"One line: when to pick this format."},"length":{"type":"object","required":["unit","min","max"],"properties":{"unit":{"type":"string","enum":["words","chars","slides"]},"min":{"type":"integer","minimum":0},"max":{"type":"integer","minimum":1},"perSlideMaxWords":{"type":"integer","description":"carousel_script / thread: words allowed per slide or post."},"titleMaxWords":{"type":"integer","description":"carousel_script: words allowed in the title (first line of slide 1)."},"captionWords":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"description":"carousel_script: the caption that goes with the slides."}}},"sections":{"type":"array","maxItems":20,"description":"In order. \"Start from a format\" writes one `[you fill: Label — guidance]` placeholder per section.","items":{"type":"object","required":["label"],"properties":{"key":{"type":"string","description":"Derived from the label when omitted."},"label":{"type":"string","maxLength":80},"guidance":{"type":"string","maxLength":1000},"required":{"type":"boolean","default":true},"minLines":{"type":"integer"},"maxLines":{"type":"integer"}}}},"hookPatterns":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300},"description":"\"[slot]\" placeholders are kept as written."},"ctaSlots":{"type":"array","maxItems":10,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"text":{"type":"string"},"placement":{"type":"string","enum":["body","first_comment","none"],"default":"body"}}}},"guardrails":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":500}},"maxHashtags":{"type":"integer","nullable":true,"minimum":0,"maximum":30},"defaultLabels":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"\"key:value\" labels every draft started from this format gets (plus the format's own `label`)."},"example":{"type":"string","nullable":true,"maxLength":20000},"source":{"type":"string","nullable":true,"maxLength":200,"description":"Where the shape came from, e.g. an import path."},"brandId":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"name":{"type":"string","maxLength":120},"format":{"type":"string","enum":["post","article","carousel_script","meme","thread"]},"platform":{"type":"string","nullable":true,"description":"e.g. \"linkedin\"; null = any platform."},"useFor":{"type":"string","nullable":true,"maxLength":300,"description":"One line: when to pick this format."},"length":{"type":"object","required":["unit","min","max"],"properties":{"unit":{"type":"string","enum":["words","chars","slides"]},"min":{"type":"integer","minimum":0},"max":{"type":"integer","minimum":1},"perSlideMaxWords":{"type":"integer","description":"carousel_script / thread: words allowed per slide or post."},"titleMaxWords":{"type":"integer","description":"carousel_script: words allowed in the title (first line of slide 1)."},"captionWords":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"description":"carousel_script: the caption that goes with the slides."}}},"sections":{"type":"array","maxItems":20,"description":"In order. \"Start from a format\" writes one `[you fill: Label — guidance]` placeholder per section.","items":{"type":"object","required":["label"],"properties":{"key":{"type":"string","description":"Derived from the label when omitted."},"label":{"type":"string","maxLength":80},"guidance":{"type":"string","maxLength":1000},"required":{"type":"boolean","default":true},"minLines":{"type":"integer"},"maxLines":{"type":"integer"}}}},"hookPatterns":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300},"description":"\"[slot]\" placeholders are kept as written."},"ctaSlots":{"type":"array","maxItems":10,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"text":{"type":"string"},"placement":{"type":"string","enum":["body","first_comment","none"],"default":"body"}}}},"guardrails":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":500}},"maxHashtags":{"type":"integer","nullable":true,"minimum":0,"maximum":30},"defaultLabels":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"\"key:value\" labels every draft started from this format gets (plus the format's own `label`)."},"example":{"type":"string","nullable":true,"maxLength":20000},"source":{"type":"string","nullable":true,"maxLength":200,"description":"Where the shape came from, e.g. an import path."},"label":{"type":"string","description":"template:<id> — every draft started from this format carries it."},"archived":{"type":"boolean"},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Missing write scope, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"},"422":{"description":"Invalid field (the message names it)"}}}},"/api/v2/text-templates/{id}":{"get":{"tags":["API v2"],"summary":"Get a format","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Format","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"name":{"type":"string","maxLength":120},"format":{"type":"string","enum":["post","article","carousel_script","meme","thread"]},"platform":{"type":"string","nullable":true,"description":"e.g. \"linkedin\"; null = any platform."},"useFor":{"type":"string","nullable":true,"maxLength":300,"description":"One line: when to pick this format."},"length":{"type":"object","required":["unit","min","max"],"properties":{"unit":{"type":"string","enum":["words","chars","slides"]},"min":{"type":"integer","minimum":0},"max":{"type":"integer","minimum":1},"perSlideMaxWords":{"type":"integer","description":"carousel_script / thread: words allowed per slide or post."},"titleMaxWords":{"type":"integer","description":"carousel_script: words allowed in the title (first line of slide 1)."},"captionWords":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"description":"carousel_script: the caption that goes with the slides."}}},"sections":{"type":"array","maxItems":20,"description":"In order. \"Start from a format\" writes one `[you fill: Label — guidance]` placeholder per section.","items":{"type":"object","required":["label"],"properties":{"key":{"type":"string","description":"Derived from the label when omitted."},"label":{"type":"string","maxLength":80},"guidance":{"type":"string","maxLength":1000},"required":{"type":"boolean","default":true},"minLines":{"type":"integer"},"maxLines":{"type":"integer"}}}},"hookPatterns":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300},"description":"\"[slot]\" placeholders are kept as written."},"ctaSlots":{"type":"array","maxItems":10,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"text":{"type":"string"},"placement":{"type":"string","enum":["body","first_comment","none"],"default":"body"}}}},"guardrails":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":500}},"maxHashtags":{"type":"integer","nullable":true,"minimum":0,"maximum":30},"defaultLabels":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"\"key:value\" labels every draft started from this format gets (plus the format's own `label`)."},"example":{"type":"string","nullable":true,"maxLength":20000},"source":{"type":"string","nullable":true,"maxLength":200,"description":"Where the shape came from, e.g. an import path."},"label":{"type":"string","description":"template:<id> — every draft started from this format carries it."},"archived":{"type":"boolean"},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Not found (or another brand than a bound key's)"}}},"patch":{"tags":["API v2"],"summary":"Update a format","description":"Only the fields sent change; null clears platform / useFor / maxHashtags / example / source. `archived: true` hides it from \"Start from a format\". A format cannot move between brands. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"format":{"type":"string","enum":["post","article","carousel_script","meme","thread"]},"platform":{"type":"string","nullable":true,"description":"e.g. \"linkedin\"; null = any platform."},"useFor":{"type":"string","nullable":true,"maxLength":300,"description":"One line: when to pick this format."},"length":{"type":"object","required":["unit","min","max"],"properties":{"unit":{"type":"string","enum":["words","chars","slides"]},"min":{"type":"integer","minimum":0},"max":{"type":"integer","minimum":1},"perSlideMaxWords":{"type":"integer","description":"carousel_script / thread: words allowed per slide or post."},"titleMaxWords":{"type":"integer","description":"carousel_script: words allowed in the title (first line of slide 1)."},"captionWords":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"description":"carousel_script: the caption that goes with the slides."}}},"sections":{"type":"array","maxItems":20,"description":"In order. \"Start from a format\" writes one `[you fill: Label — guidance]` placeholder per section.","items":{"type":"object","required":["label"],"properties":{"key":{"type":"string","description":"Derived from the label when omitted."},"label":{"type":"string","maxLength":80},"guidance":{"type":"string","maxLength":1000},"required":{"type":"boolean","default":true},"minLines":{"type":"integer"},"maxLines":{"type":"integer"}}}},"hookPatterns":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300},"description":"\"[slot]\" placeholders are kept as written."},"ctaSlots":{"type":"array","maxItems":10,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"text":{"type":"string"},"placement":{"type":"string","enum":["body","first_comment","none"],"default":"body"}}}},"guardrails":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":500}},"maxHashtags":{"type":"integer","nullable":true,"minimum":0,"maximum":30},"defaultLabels":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"\"key:value\" labels every draft started from this format gets (plus the format's own `label`)."},"example":{"type":"string","nullable":true,"maxLength":20000},"source":{"type":"string","nullable":true,"maxLength":200,"description":"Where the shape came from, e.g. an import path."},"archived":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"name":{"type":"string","maxLength":120},"format":{"type":"string","enum":["post","article","carousel_script","meme","thread"]},"platform":{"type":"string","nullable":true,"description":"e.g. \"linkedin\"; null = any platform."},"useFor":{"type":"string","nullable":true,"maxLength":300,"description":"One line: when to pick this format."},"length":{"type":"object","required":["unit","min","max"],"properties":{"unit":{"type":"string","enum":["words","chars","slides"]},"min":{"type":"integer","minimum":0},"max":{"type":"integer","minimum":1},"perSlideMaxWords":{"type":"integer","description":"carousel_script / thread: words allowed per slide or post."},"titleMaxWords":{"type":"integer","description":"carousel_script: words allowed in the title (first line of slide 1)."},"captionWords":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"description":"carousel_script: the caption that goes with the slides."}}},"sections":{"type":"array","maxItems":20,"description":"In order. \"Start from a format\" writes one `[you fill: Label — guidance]` placeholder per section.","items":{"type":"object","required":["label"],"properties":{"key":{"type":"string","description":"Derived from the label when omitted."},"label":{"type":"string","maxLength":80},"guidance":{"type":"string","maxLength":1000},"required":{"type":"boolean","default":true},"minLines":{"type":"integer"},"maxLines":{"type":"integer"}}}},"hookPatterns":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300},"description":"\"[slot]\" placeholders are kept as written."},"ctaSlots":{"type":"array","maxItems":10,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"text":{"type":"string"},"placement":{"type":"string","enum":["body","first_comment","none"],"default":"body"}}}},"guardrails":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":500}},"maxHashtags":{"type":"integer","nullable":true,"minimum":0,"maximum":30},"defaultLabels":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"\"key:value\" labels every draft started from this format gets (plus the format's own `label`)."},"example":{"type":"string","nullable":true,"maxLength":20000},"source":{"type":"string","nullable":true,"maxLength":200,"description":"Where the shape came from, e.g. an import path."},"label":{"type":"string","description":"template:<id> — every draft started from this format carries it."},"archived":{"type":"boolean"},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Not found"},"422":{"description":"Invalid field"}}},"delete":{"tags":["API v2"],"summary":"Delete a format","description":"Drafts started from it keep their text, labels and format. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ deleted: id }"},"404":{"description":"Not found"}}}},"/api/v2/growth-triggers":{"get":{"tags":["API v2"],"summary":"List comment-to-get triggers","description":"The brand's keyword triggers: a comment matching a keyword gets a public reply and/or a private reply (DM).","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"responses":{"200":{"description":"Triggers","content":{"application/json":{"schema":{"type":"object","properties":{"triggers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"active":{"type":"boolean"},"name":{"type":"string"},"keywords":{"type":"array","minItems":1,"description":"Case-insensitive. exact = the whole comment; startsWith = its start; contains = anywhere (substring, so \"hi\" also matches \"this\").","items":{"type":"object","required":["value","matchType"],"properties":{"value":{"type":"string"},"matchType":{"type":"string","enum":["exact","contains","startsWith"]}}}},"replyText":{"type":"string","description":"Public reply. {{name}} = the commenter, {{link}} = `link` with UTM tags. Must not contain a keyword (it would trigger itself)."},"dmText":{"type":"string","description":"Private reply (Instagram and Facebook only; refused on an account of another platform)."},"accountId":{"type":"string","description":"A connected account id (GET /api/v2/accounts); omitted = every account of the brand."},"postIds":{"type":"array","items":{"type":"string"},"description":"Only comments on these posts; omitted = all posts."},"priority":{"type":"number","description":"Higher is checked first; the first matching trigger wins."},"repeatPolicy":{"type":"string","enum":["once_per_commenter","every_comment"],"default":"once_per_commenter"},"replyVariations":{"type":"array","items":{"type":"string"},"description":"Alternatives picked at random with replyText."},"dmVariations":{"type":"array","items":{"type":"string"}},"delaySeconds":{"type":"number","minimum":0,"description":"Wait before replying; capped at 20 at send time."},"campaignKey":{"type":"string","description":"utm_campaign for {{link}}, and the campaign column of the logs."},"link":{"type":"string","format":"uri","description":"http(s) URL behind {{link}}."},"maxSends":{"type":"integer","minimum":1,"description":"After this many sends, reply only overCapText."},"overCapText":{"type":"string"},"counts":{"type":"object","properties":{"matched":{"type":"integer"},"replies":{"type":"integer"},"dms":{"type":"integer"},"sends":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"403":{"description":"Growth not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}},"post":{"tags":["API v2"],"summary":"Create a comment-to-get trigger (inactive)","description":"Created in `brandId` (default: the active brand). Always created INACTIVE (`active` is refused): a person reviews it and turns it on in Growth, or with PATCH { active: true } and the publish scope. Requires the write scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","keywords"],"properties":{"name":{"type":"string"},"keywords":{"type":"array","minItems":1,"description":"Case-insensitive. exact = the whole comment; startsWith = its start; contains = anywhere (substring, so \"hi\" also matches \"this\").","items":{"type":"object","required":["value","matchType"],"properties":{"value":{"type":"string"},"matchType":{"type":"string","enum":["exact","contains","startsWith"]}}}},"replyText":{"type":"string","description":"Public reply. {{name}} = the commenter, {{link}} = `link` with UTM tags. Must not contain a keyword (it would trigger itself)."},"dmText":{"type":"string","description":"Private reply (Instagram and Facebook only; refused on an account of another platform)."},"accountId":{"type":"string","description":"A connected account id (GET /api/v2/accounts); omitted = every account of the brand."},"postIds":{"type":"array","items":{"type":"string"},"description":"Only comments on these posts; omitted = all posts."},"priority":{"type":"number","description":"Higher is checked first; the first matching trigger wins."},"repeatPolicy":{"type":"string","enum":["once_per_commenter","every_comment"],"default":"once_per_commenter"},"replyVariations":{"type":"array","items":{"type":"string"},"description":"Alternatives picked at random with replyText."},"dmVariations":{"type":"array","items":{"type":"string"}},"delaySeconds":{"type":"number","minimum":0,"description":"Wait before replying; capped at 20 at send time."},"campaignKey":{"type":"string","description":"utm_campaign for {{link}}, and the campaign column of the logs."},"link":{"type":"string","format":"uri","description":"http(s) URL behind {{link}}."},"maxSends":{"type":"integer","minimum":1,"description":"After this many sends, reply only overCapText."},"overCapText":{"type":"string"},"brandId":{"type":"string"}}}}}},"responses":{"201":{"description":"Created (inactive)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"active":{"type":"boolean"},"name":{"type":"string"},"keywords":{"type":"array","minItems":1,"description":"Case-insensitive. exact = the whole comment; startsWith = its start; contains = anywhere (substring, so \"hi\" also matches \"this\").","items":{"type":"object","required":["value","matchType"],"properties":{"value":{"type":"string"},"matchType":{"type":"string","enum":["exact","contains","startsWith"]}}}},"replyText":{"type":"string","description":"Public reply. {{name}} = the commenter, {{link}} = `link` with UTM tags. Must not contain a keyword (it would trigger itself)."},"dmText":{"type":"string","description":"Private reply (Instagram and Facebook only; refused on an account of another platform)."},"accountId":{"type":"string","description":"A connected account id (GET /api/v2/accounts); omitted = every account of the brand."},"postIds":{"type":"array","items":{"type":"string"},"description":"Only comments on these posts; omitted = all posts."},"priority":{"type":"number","description":"Higher is checked first; the first matching trigger wins."},"repeatPolicy":{"type":"string","enum":["once_per_commenter","every_comment"],"default":"once_per_commenter"},"replyVariations":{"type":"array","items":{"type":"string"},"description":"Alternatives picked at random with replyText."},"dmVariations":{"type":"array","items":{"type":"string"}},"delaySeconds":{"type":"number","minimum":0,"description":"Wait before replying; capped at 20 at send time."},"campaignKey":{"type":"string","description":"utm_campaign for {{link}}, and the campaign column of the logs."},"link":{"type":"string","format":"uri","description":"http(s) URL behind {{link}}."},"maxSends":{"type":"integer","minimum":1,"description":"After this many sends, reply only overCapText."},"overCapText":{"type":"string"},"counts":{"type":"object","properties":{"matched":{"type":"integer"},"replies":{"type":"integer"},"dms":{"type":"integer"},"sends":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Missing write scope, Growth not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"},"422":{"description":"Invalid field, DM on a platform without private replies, keyword inside the reply text, or a bad link"}}}},"/api/v2/growth-triggers/{id}":{"get":{"tags":["API v2"],"summary":"Get a comment-to-get trigger","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"responses":{"200":{"description":"Trigger","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"active":{"type":"boolean"},"name":{"type":"string"},"keywords":{"type":"array","minItems":1,"description":"Case-insensitive. exact = the whole comment; startsWith = its start; contains = anywhere (substring, so \"hi\" also matches \"this\").","items":{"type":"object","required":["value","matchType"],"properties":{"value":{"type":"string"},"matchType":{"type":"string","enum":["exact","contains","startsWith"]}}}},"replyText":{"type":"string","description":"Public reply. {{name}} = the commenter, {{link}} = `link` with UTM tags. Must not contain a keyword (it would trigger itself)."},"dmText":{"type":"string","description":"Private reply (Instagram and Facebook only; refused on an account of another platform)."},"accountId":{"type":"string","description":"A connected account id (GET /api/v2/accounts); omitted = every account of the brand."},"postIds":{"type":"array","items":{"type":"string"},"description":"Only comments on these posts; omitted = all posts."},"priority":{"type":"number","description":"Higher is checked first; the first matching trigger wins."},"repeatPolicy":{"type":"string","enum":["once_per_commenter","every_comment"],"default":"once_per_commenter"},"replyVariations":{"type":"array","items":{"type":"string"},"description":"Alternatives picked at random with replyText."},"dmVariations":{"type":"array","items":{"type":"string"}},"delaySeconds":{"type":"number","minimum":0,"description":"Wait before replying; capped at 20 at send time."},"campaignKey":{"type":"string","description":"utm_campaign for {{link}}, and the campaign column of the logs."},"link":{"type":"string","format":"uri","description":"http(s) URL behind {{link}}."},"maxSends":{"type":"integer","minimum":1,"description":"After this many sends, reply only overCapText."},"overCapText":{"type":"string"},"counts":{"type":"object","properties":{"matched":{"type":"integer"},"replies":{"type":"integer"},"dms":{"type":"integer"},"sends":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Not found in this brand"}}},"patch":{"tags":["API v2"],"summary":"Update a comment-to-get trigger","description":"Only the fields sent change. `active: true` turns it on (it then replies to and DMs real people) and also needs the publish scope; `active: false` pauses it. A trigger cannot move between brands. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"keywords":{"type":"array","minItems":1,"description":"Case-insensitive. exact = the whole comment; startsWith = its start; contains = anywhere (substring, so \"hi\" also matches \"this\").","items":{"type":"object","required":["value","matchType"],"properties":{"value":{"type":"string"},"matchType":{"type":"string","enum":["exact","contains","startsWith"]}}}},"replyText":{"type":"string","description":"Public reply. {{name}} = the commenter, {{link}} = `link` with UTM tags. Must not contain a keyword (it would trigger itself)."},"dmText":{"type":"string","description":"Private reply (Instagram and Facebook only; refused on an account of another platform)."},"accountId":{"type":"string","description":"A connected account id (GET /api/v2/accounts); omitted = every account of the brand."},"postIds":{"type":"array","items":{"type":"string"},"description":"Only comments on these posts; omitted = all posts."},"priority":{"type":"number","description":"Higher is checked first; the first matching trigger wins."},"repeatPolicy":{"type":"string","enum":["once_per_commenter","every_comment"],"default":"once_per_commenter"},"replyVariations":{"type":"array","items":{"type":"string"},"description":"Alternatives picked at random with replyText."},"dmVariations":{"type":"array","items":{"type":"string"}},"delaySeconds":{"type":"number","minimum":0,"description":"Wait before replying; capped at 20 at send time."},"campaignKey":{"type":"string","description":"utm_campaign for {{link}}, and the campaign column of the logs."},"link":{"type":"string","format":"uri","description":"http(s) URL behind {{link}}."},"maxSends":{"type":"integer","minimum":1,"description":"After this many sends, reply only overCapText."},"overCapText":{"type":"string"},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"A brand id, or \"personal\"."},"active":{"type":"boolean"},"name":{"type":"string"},"keywords":{"type":"array","minItems":1,"description":"Case-insensitive. exact = the whole comment; startsWith = its start; contains = anywhere (substring, so \"hi\" also matches \"this\").","items":{"type":"object","required":["value","matchType"],"properties":{"value":{"type":"string"},"matchType":{"type":"string","enum":["exact","contains","startsWith"]}}}},"replyText":{"type":"string","description":"Public reply. {{name}} = the commenter, {{link}} = `link` with UTM tags. Must not contain a keyword (it would trigger itself)."},"dmText":{"type":"string","description":"Private reply (Instagram and Facebook only; refused on an account of another platform)."},"accountId":{"type":"string","description":"A connected account id (GET /api/v2/accounts); omitted = every account of the brand."},"postIds":{"type":"array","items":{"type":"string"},"description":"Only comments on these posts; omitted = all posts."},"priority":{"type":"number","description":"Higher is checked first; the first matching trigger wins."},"repeatPolicy":{"type":"string","enum":["once_per_commenter","every_comment"],"default":"once_per_commenter"},"replyVariations":{"type":"array","items":{"type":"string"},"description":"Alternatives picked at random with replyText."},"dmVariations":{"type":"array","items":{"type":"string"}},"delaySeconds":{"type":"number","minimum":0,"description":"Wait before replying; capped at 20 at send time."},"campaignKey":{"type":"string","description":"utm_campaign for {{link}}, and the campaign column of the logs."},"link":{"type":"string","format":"uri","description":"http(s) URL behind {{link}}."},"maxSends":{"type":"integer","minimum":1,"description":"After this many sends, reply only overCapText."},"overCapText":{"type":"string"},"counts":{"type":"object","properties":{"matched":{"type":"integer"},"replies":{"type":"integer"},"dms":{"type":"integer"},"sends":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Missing write scope (or publish scope for active: true)"},"404":{"description":"Not found in this brand"},"422":{"description":"Invalid field or config"}}},"delete":{"tags":["API v2"],"summary":"Delete a comment-to-get trigger","description":"Its logs stay. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"responses":{"200":{"description":"{ deleted: id }"},"404":{"description":"Not found in this brand"}}}},"/api/v2/growth-triggers/{id}/stats":{"get":{"tags":["API v2"],"summary":"Comment-to-get trigger stats","description":"Matched comments, unique commenters, replies, DMs, failures and sends past the cap, in total and per UTC day.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"responses":{"200":{"description":"Stats","content":{"application/json":{"schema":{"type":"object","properties":{"stats":{"type":"object","properties":{"matched":{"type":"integer"},"uniqueCommenters":{"type":"integer"},"replies":{"type":"integer"},"dms":{"type":"integer"},"failures":{"type":"integer"},"overCap":{"type":"integer"},"byDay":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","description":"YYYY-MM-DD (UTC)"},"matched":{"type":"integer"},"replies":{"type":"integer"},"dms":{"type":"integer"},"failures":{"type":"integer"}}}},"truncated":{"type":"boolean","description":"True when the trigger has more than 5,000 log rows; the stats cover the latest 5,000."}}}}}}}},"404":{"description":"Not found in this brand"}}}},"/api/v2/ads/offers":{"get":{"tags":["API v2"],"summary":"List ad platform offers","description":"The brand's new-advertiser offers per ad network, one row per ad account (or per network not connected yet), with spend-to-unlock progress from synced ad insights. Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands). Required for an account-wide key; a brand-bound key is pinned to its brand and any other value is 403."}],"responses":{"200":{"description":"Offers","content":{"application/json":{"schema":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Row id: pass it to PATCH /api/v2/ads/offers/{claimId}."},"network":{"type":"string","enum":["googleads","redditads","tiktokads","xads","microsoftads","linkedinads","chatgptads","snapchatads","metaads","pinterestads"]},"adAccountId":{"type":"string","nullable":true,"description":"The ad network's account id; null for a network not connected yet."},"connected":{"type":"boolean"},"planned":{"type":"boolean","description":"True for a network the brand has not connected: claim at sign-up, before creating the account."},"currency":{"type":"string"},"status":{"type":"string","enum":["not_claimed","claimed","earned","expired","ineligible"],"description":"Derived: the stored status, or expired once the deadline passed unearned."},"storedStatus":{"type":"string","enum":["not_claimed","claimed","earned","expired","ineligible"]},"offer":{"type":"object","properties":{"offerKey":{"type":"string"},"title":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"spendMinor":{"type":"integer","description":"Minor units (cents) in `currency`."},"awardMinor":{"type":"integer","description":"Minor units (cents) in `currency`."}}}},"claimTiming":{"type":"string","description":"at_signup = claim from the offer page before creating the account."},"countingStart":{"type":"string"},"claimWindowDays":{"type":"integer","nullable":true},"spendWindowDays":{"type":"integer"},"expiryDaysAfterAward":{"type":"integer","nullable":true},"perBrandRule":{"type":"string"},"howToClaim":{"type":"array","items":{"type":"string"}},"sourceUrl":{"type":"string","nullable":true},"checkedAt":{"type":"string","nullable":true,"description":"When the terms were last checked; null = not verified."},"noPublicOffer":{"type":"boolean"}}},"tierIndex":{"type":"integer","nullable":true},"accountCreatedAt":{"type":"string","format":"date-time","nullable":true},"claimedAt":{"type":"string","format":"date-time","nullable":true},"awardedAt":{"type":"string","format":"date-time","nullable":true},"countingStartsAt":{"type":"string","format":"date-time","nullable":true},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"Spend the target by this date."},"claimDeadline":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"daysLeft":{"type":"integer","nullable":true},"spentMinor":{"type":"integer","description":"Minor units (cents) in `currency`."},"targetSpendMinor":{"type":"integer","nullable":true,"description":"Minor units (cents) in `currency`."},"awardMinor":{"type":"integer","nullable":true,"description":"Minor units (cents) in `currency`."},"toGoMinor":{"type":"integer","nullable":true,"description":"Minor units (cents) in `currency`."},"perDayMinor":{"type":"integer","nullable":true,"description":"Minor units (cents) in `currency`."},"warn":{"type":"boolean","description":"The deadline is close (the configured warning window)."},"pacing":{"type":"string","nullable":true,"description":"e.g. \"$400 to go, about $13.33/day to unlock by Dec 3, 2026\"."},"notes":{"type":"string","nullable":true},"hasEvidence":{"type":"boolean","description":"A screenshot is attached (dashboard only)."}}}},"canEdit":{"type":"boolean","description":"The caller is an owner or admin of the brand."},"warnDaysBeforeDeadline":{"type":"integer"}}}}}},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"},"422":{"description":"`brandId` missing for an account-wide key"}}}},"/api/v2/ads/offers/{claimId}":{"patch":{"tags":["API v2"],"summary":"Record an ad platform offer claim","description":"Updates one row (`claimId` = a row `id` from the list; the first update of a row creates its claim). Only the fields sent change; dates are clamped to 2000..tomorrow. Owners and admins of the brand only. A record only: it never creates, activates or funds an ad. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"claimId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"brandId":{"type":"string","description":"A brand id (GET /api/v2/brands). Required for an account-wide key."},"status":{"type":"string","enum":["not_claimed","claimed","earned","expired","ineligible"]},"claimedAt":{"type":"string","nullable":true,"description":"YYYY-MM-DD (or ISO timestamp); null clears it."},"notes":{"type":"string","maxLength":1000,"nullable":true}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"offer":{"type":"object","properties":{"id":{"type":"string","description":"Row id: pass it to PATCH /api/v2/ads/offers/{claimId}."},"network":{"type":"string","enum":["googleads","redditads","tiktokads","xads","microsoftads","linkedinads","chatgptads","snapchatads","metaads","pinterestads"]},"adAccountId":{"type":"string","nullable":true,"description":"The ad network's account id; null for a network not connected yet."},"connected":{"type":"boolean"},"planned":{"type":"boolean","description":"True for a network the brand has not connected: claim at sign-up, before creating the account."},"currency":{"type":"string"},"status":{"type":"string","enum":["not_claimed","claimed","earned","expired","ineligible"],"description":"Derived: the stored status, or expired once the deadline passed unearned."},"storedStatus":{"type":"string","enum":["not_claimed","claimed","earned","expired","ineligible"]},"offer":{"type":"object","properties":{"offerKey":{"type":"string"},"title":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"spendMinor":{"type":"integer","description":"Minor units (cents) in `currency`."},"awardMinor":{"type":"integer","description":"Minor units (cents) in `currency`."}}}},"claimTiming":{"type":"string","description":"at_signup = claim from the offer page before creating the account."},"countingStart":{"type":"string"},"claimWindowDays":{"type":"integer","nullable":true},"spendWindowDays":{"type":"integer"},"expiryDaysAfterAward":{"type":"integer","nullable":true},"perBrandRule":{"type":"string"},"howToClaim":{"type":"array","items":{"type":"string"}},"sourceUrl":{"type":"string","nullable":true},"checkedAt":{"type":"string","nullable":true,"description":"When the terms were last checked; null = not verified."},"noPublicOffer":{"type":"boolean"}}},"tierIndex":{"type":"integer","nullable":true},"accountCreatedAt":{"type":"string","format":"date-time","nullable":true},"claimedAt":{"type":"string","format":"date-time","nullable":true},"awardedAt":{"type":"string","format":"date-time","nullable":true},"countingStartsAt":{"type":"string","format":"date-time","nullable":true},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"Spend the target by this date."},"claimDeadline":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"daysLeft":{"type":"integer","nullable":true},"spentMinor":{"type":"integer","description":"Minor units (cents) in `currency`."},"targetSpendMinor":{"type":"integer","nullable":true,"description":"Minor units (cents) in `currency`."},"awardMinor":{"type":"integer","nullable":true,"description":"Minor units (cents) in `currency`."},"toGoMinor":{"type":"integer","nullable":true,"description":"Minor units (cents) in `currency`."},"perDayMinor":{"type":"integer","nullable":true,"description":"Minor units (cents) in `currency`."},"warn":{"type":"boolean","description":"The deadline is close (the configured warning window)."},"pacing":{"type":"string","nullable":true,"description":"e.g. \"$400 to go, about $13.33/day to unlock by Dec 3, 2026\"."},"notes":{"type":"string","nullable":true},"hasEvidence":{"type":"boolean","description":"A screenshot is attached (dashboard only)."}}}}}}}},"403":{"description":"Missing write scope, not an owner or admin, or another brand for a brand-bound key"},"404":{"description":"Unknown brand or offer row"},"422":{"description":"Invalid field"}}}},"/api/v2/ads/leads/{leadId}/booking-slots":{"get":{"tags":["API v2"],"summary":"List free times to book a call with a lead","description":"The next free times on the brand's connected Google or Microsoft calendar, under the brand's booking rules (call length, buffers, open hours, minimum notice). Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,32}$"},"description":"The Meta lead id (leadgen id)."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands). Required for an account-wide key; a brand-bound key is pinned to its brand and any other value is 403."}],"responses":{"200":{"description":"Free slots","content":{"application/json":{"schema":{"type":"object","properties":{"slots":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}}},"timeZone":{"type":"string"},"durationMinutes":{"type":"integer"},"conferencing":{"type":"string","enum":["google_meet","teams"]}}}}}},"403":{"description":"Missing scope, no permission on the lead, or another brand for a brand-bound key"},"404":{"description":"Unknown brand or lead"},"422":{"description":"Invalid field, or the brand has no connected calendar"},"503":{"description":"The calendar could not be read or written right now; retry later"}}}},"/api/v2/ads/leads/{leadId}/book":{"post":{"tags":["API v2"],"summary":"Book a call with a lead","description":"Sends the lead a calendar invite with a Google Meet or Microsoft Teams link at one of the free slots, and marks the lead booked. The slot is re-checked first (409 when it was taken). Requires the write scope. Moves no money.","security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,32}$"},"description":"The Meta lead id (leadgen id)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["start"],"properties":{"brandId":{"type":"string","description":"A brand id (GET /api/v2/brands). Required for an account-wide key."},"start":{"type":"string","format":"date-time","description":"A slot `start` from booking-slots."},"attendeeEmail":{"type":"string","format":"email","maxLength":320,"description":"Only when the lead has no email address on file."}}}}}},"responses":{"201":{"description":"Booked","content":{"application/json":{"schema":{"type":"object","properties":{"booking":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"meetingUrl":{"type":"string","nullable":true},"eventLink":{"type":"string","nullable":true},"status":{"type":"string","enum":["booked","cancelled"]},"leadStatusUpdated":{"type":"boolean"}}}}}}}},"403":{"description":"Missing scope, no permission on the lead, or another brand for a brand-bound key"},"404":{"description":"Unknown brand or lead"},"409":{"description":"The slot is no longer free, or the lead already has a call booked"},"422":{"description":"Invalid field, or the brand has no connected calendar"},"503":{"description":"The calendar could not be read or written right now; retry later"}}}},"/api/v2/brands/{id}/business-details":{"get":{"tags":["API v2"],"summary":"Get a brand's business details","description":"Legal name, registered address, website, currency and timezone: what ad networks ask for when you open an ads account. Membership in the brand's org is enough. The tax id is never returned; `hasTaxId` says whether one is on file.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"responses":{"200":{"description":"Business details (fields are null until set)","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"brandName":{"type":"string"},"legalName":{"type":"string","nullable":true},"registeredAddress":{"type":"object","required":["line1","city","region","postalCode","country"],"description":"Replaced as a whole when sent.","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":200},"region":{"type":"string","maxLength":200,"description":"State, province or county."},"postalCode":{"type":"string","maxLength":20},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"2-letter ISO country code.","example":"US"}},"nullable":true},"website":{"type":"string","nullable":true,"description":"The brand website from Brand › Overview (set it with PATCH /api/v2/brand/intelligence)."},"currency":{"type":"string","nullable":true,"example":"USD"},"timezone":{"type":"string","nullable":true,"example":"America/New_York"},"hasTaxId":{"type":"boolean","description":"Whether a tax id is on file. The tax id itself is never returned by the API."},"copiedFromBrandId":{"type":"string","nullable":true,"description":"Set when the details were copied from another brand."},"updatedAt":{"type":"string","format":"date-time","nullable":true}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"A brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"}}},"patch":{"tags":["API v2"],"summary":"Update a brand's business details","description":"Changes only the fields sent; a brand with no details yet needs all four. Requires the write (or admin) scope and owner / admin / editor in the brand's org. The tax id cannot be set through the API: any tax field is a 422. A brand owner or admin manages it in flayr.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Send at least one field. Unknown fields and tax fields are a 422.","properties":{"legalName":{"type":"string","maxLength":200},"registeredAddress":{"type":"object","required":["line1","city","region","postalCode","country"],"description":"Replaced as a whole when sent.","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":200},"region":{"type":"string","maxLength":200,"description":"State, province or county."},"postalCode":{"type":"string","maxLength":20},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"2-letter ISO country code.","example":"US"}}},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"3-letter ISO currency code.","example":"USD"},"timezone":{"type":"string","description":"IANA time zone.","example":"America/New_York"}}},"example":{"legalName":"Acme Hair Studio LLC","currency":"USD","timezone":"America/Chicago"}}}},"responses":{"200":{"description":"Updated; same shape as GET","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"brandName":{"type":"string"},"legalName":{"type":"string","nullable":true},"registeredAddress":{"type":"object","required":["line1","city","region","postalCode","country"],"description":"Replaced as a whole when sent.","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":200},"region":{"type":"string","maxLength":200,"description":"State, province or county."},"postalCode":{"type":"string","maxLength":20},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"2-letter ISO country code.","example":"US"}},"nullable":true},"website":{"type":"string","nullable":true,"description":"The brand website from Brand › Overview (set it with PATCH /api/v2/brand/intelligence)."},"currency":{"type":"string","nullable":true,"example":"USD"},"timezone":{"type":"string","nullable":true,"example":"America/New_York"},"hasTaxId":{"type":"boolean","description":"Whether a tax id is on file. The tax id itself is never returned by the API."},"copiedFromBrandId":{"type":"string","nullable":true,"description":"Set when the details were copied from another brand."},"updatedAt":{"type":"string","format":"date-time","nullable":true}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing write scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or the key owner cannot edit it"},"422":{"description":"A tax field, an unknown field, a missing required field, or a bad currency / country / timezone"}}}},"/api/v2/brands/{id}/mailbox":{"get":{"tags":["API v2"],"summary":"Get a brand's connected mailbox","description":"The business's own mailbox (Gmail, Microsoft or IMAP) that sends lead follow-ups, its daily send cap and the fallback. Membership in the brand's org is enough.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"responses":{"200":{"description":"The mailbox (null when none is connected)","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"canEdit":{"type":"boolean"},"canConnect":{"type":"boolean","description":"False until the brand has its own Zernio profile (connect a social account first)."},"mailbox":{"type":"object","nullable":true,"properties":{"email":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft","imap"],"nullable":true},"status":{"type":"string","enum":["connected","disconnected"]},"useForLeads":{"type":"boolean","description":"Lead follow-ups go out from this mailbox."},"fallback":{"type":"string","enum":["resend","hold"],"description":"When the mailbox cannot send: resend = flayr's own sender, hold = do not send."},"trackOpens":{"type":"boolean"},"trackLinks":{"type":"boolean"},"connectedAt":{"type":"string","format":"date-time","nullable":true},"sendCap":{"type":"object","description":"The provider's daily send cap, as Zernio last reported it.","properties":{"limit":{"type":"integer","nullable":true},"remaining":{"type":"integer","nullable":true},"resetsAt":{"type":"string","nullable":true}}},"lastError":{"type":"string","nullable":true}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, no mailbox, bad input); `error` says why"}}}},"/api/v2/brands/{id}/mailbox/connect-link":{"post":{"tags":["API v2"],"summary":"Get a link to connect a brand's mailbox","description":"A one-time link to connect the business's own mailbox. The mailbox owner opens it signed in to flayr and approves with their provider; flayr then checks the mailbox is on this brand before saving it. Scope `write`; owner / admin / editor.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","description":"Pre-fills the mailbox address."},"reconnect":{"type":"boolean","description":"Refresh the brand's existing connection."}}}}}},"responses":{"200":{"description":"The link","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"expiresAt":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, no mailbox, bad input); `error` says why"}}}},"/api/v2/brands/{id}/mailbox/test":{"post":{"tags":["API v2"],"summary":"Send a test email from a brand's mailbox","description":"Sends one test email from the connected mailbox to the key owner's own address. Never falls back to flayr's sender. Scope `write`; owner / admin / editor.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"},"from":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true,"description":"Why it did not send, e.g. cap_reached, disconnected, send_failed."}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, no mailbox, bad input); `error` says why"}}}},"/api/v2/brands/{id}/mailbox/threads":{"get":{"tags":["API v2"],"summary":"List a contact's email thread with a brand","description":"The threads with one contact in the brand's real mailbox, plus what flayr sent them from it (opens, clicks, bounces, latest reply).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."},{"name":"email","in":"query","required":true,"schema":{"type":"string"},"description":"The contact's email address."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Threads and flayr-sent messages","content":{"application/json":{"schema":{"type":"object","properties":{"contactEmail":{"type":"string"},"threads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"participants":{"type":"array","items":{"type":"string"}},"messageCount":{"type":"integer"},"snippet":{"type":"string"},"latestAt":{"type":"string"}}}},"nextCursor":{"type":"string","nullable":true},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"subject":{"type":"string"},"status":{"type":"string"},"sentAt":{"type":"string","format":"date-time"},"threadId":{"type":"string","nullable":true},"openCount":{"type":"integer"},"clickCount":{"type":"integer"},"bouncedAt":{"type":"string","format":"date-time","nullable":true},"repliedAt":{"type":"string","format":"date-time","nullable":true},"lastReplySnippet":{"type":"string","nullable":true}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, no mailbox, bad input); `error` says why"}}}},"/api/v2/brands/{id}/sending-identity":{"get":{"tags":["API v2"],"summary":"Get a brand's sending identity","description":"Who the brand's lead follow-ups come from, the domain's DNS records, verification, warm-up and health, and a preview of each From line. Membership in the brand's org is enough.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"responses":{"200":{"description":"The identity","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"canEdit":{"type":"boolean"},"configured":{"type":"boolean","description":"False until someone saves an identity; the brand then sends as before."},"mode":{"type":"string","enum":["flayr","domain","mailbox"]},"fromName":{"type":"string","nullable":true,"description":"Display name; the brand name when null."},"replyTo":{"type":"string","nullable":true},"repliesTo":{"type":"string","enum":["brand","flayr"],"description":"flayr = replies go to the brand's flayr inbound address."},"inboundAddress":{"type":"string","nullable":true},"domain":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"fromAddress":{"type":"string"},"status":{"type":"string","enum":["not_started","pending","verified","failed","temporary_failure"]},"records":{"type":"array","description":"DNS records to publish (SPF, DKIM, return path), plus a recommended DMARC record that is not checked.","items":{"type":"object","properties":{"record":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"ttl":{"type":"string","nullable":true},"priority":{"type":"integer","nullable":true},"status":{"type":"string","nullable":true}}}},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"lastCheckedAt":{"type":"string","format":"date-time","nullable":true},"error":{"type":"string","nullable":true},"warmup":{"type":"object","properties":{"dailyLimit":{"type":"integer","nullable":true},"sentToday":{"type":"integer"}}},"health":{"type":"object","properties":{"sent":{"type":"integer"},"bounces":{"type":"integer"},"complaints":{"type":"integer"},"pausedAt":{"type":"string","format":"date-time","nullable":true},"pauseReason":{"type":"string","nullable":true}}}}},"mailbox":{"type":"object","nullable":true,"properties":{"email":{"type":"string"},"connected":{"type":"boolean"}}},"preview":{"type":"object","properties":{"flayr":{"type":"object","properties":{"from":{"type":"string"},"replyTo":{"type":"string","nullable":true}}},"domain":{"type":"object","properties":{"from":{"type":"string"},"replyTo":{"type":"string","nullable":true}},"nullable":true}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, bad input, domain not added); `error` says why"}}},"put":{"tags":["API v2"],"summary":"Set a brand's sending identity","description":"Choose flayr (default: \"<Brand> via flayr\"), domain (the brand's own domain, used only once verified) or mailbox (the connected mailbox). An empty string clears fromName or replyTo. Scope `write`; owner / admin / editor of the brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["flayr","domain","mailbox"]},"fromName":{"type":"string","maxLength":120},"replyTo":{"type":"string","maxLength":320},"repliesTo":{"type":"string","enum":["brand","flayr"]},"fromLocalPart":{"type":"string","maxLength":64,"description":"The part before the @ on the brand domain (default hello)."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"canEdit":{"type":"boolean"},"configured":{"type":"boolean","description":"False until someone saves an identity; the brand then sends as before."},"mode":{"type":"string","enum":["flayr","domain","mailbox"]},"fromName":{"type":"string","nullable":true,"description":"Display name; the brand name when null."},"replyTo":{"type":"string","nullable":true},"repliesTo":{"type":"string","enum":["brand","flayr"],"description":"flayr = replies go to the brand's flayr inbound address."},"inboundAddress":{"type":"string","nullable":true},"domain":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"fromAddress":{"type":"string"},"status":{"type":"string","enum":["not_started","pending","verified","failed","temporary_failure"]},"records":{"type":"array","description":"DNS records to publish (SPF, DKIM, return path), plus a recommended DMARC record that is not checked.","items":{"type":"object","properties":{"record":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"ttl":{"type":"string","nullable":true},"priority":{"type":"integer","nullable":true},"status":{"type":"string","nullable":true}}}},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"lastCheckedAt":{"type":"string","format":"date-time","nullable":true},"error":{"type":"string","nullable":true},"warmup":{"type":"object","properties":{"dailyLimit":{"type":"integer","nullable":true},"sentToday":{"type":"integer"}}},"health":{"type":"object","properties":{"sent":{"type":"integer"},"bounces":{"type":"integer"},"complaints":{"type":"integer"},"pausedAt":{"type":"string","format":"date-time","nullable":true},"pauseReason":{"type":"string","nullable":true}}}}},"mailbox":{"type":"object","nullable":true,"properties":{"email":{"type":"string"},"connected":{"type":"boolean"}}},"preview":{"type":"object","properties":{"flayr":{"type":"object","properties":{"from":{"type":"string"},"replyTo":{"type":"string","nullable":true}}},"domain":{"type":"object","properties":{"from":{"type":"string"},"replyTo":{"type":"string","nullable":true}},"nullable":true}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, bad input, domain not added); `error` says why"}}}},"/api/v2/brands/{id}/sending-identity/domain":{"post":{"tags":["API v2"],"summary":"Add a brand's sending domain","description":"Registers the domain with flayr's email provider. Publish the records from GET …/sending-identity, then verify. Nothing is sent from it until verified. One brand per domain. Scope `write`; owner / admin / editor of the brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["domain"],"properties":{"domain":{"type":"string","description":"e.g. example.com"},"fromLocalPart":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["not_started","pending","verified","failed","temporary_failure"]}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, bad input, domain not added); `error` says why"}}},"delete":{"tags":["API v2"],"summary":"Remove a brand's sending domain","description":"Removes the domain; a brand in domain mode goes back to flayr. Scope `write`; owner / admin / editor of the brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, bad input, domain not added); `error` says why"}}}},"/api/v2/brands/{id}/sending-identity/domain/verify":{"post":{"tags":["API v2"],"summary":"Check a brand's sending domain","description":"Asks the provider to check the DNS records now. `pending` while DNS propagates. Scope `write`; owner / admin / editor of the brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","pending","verified","failed","temporary_failure"]}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, bad input, domain not added); `error` says why"}}}},"/api/v2/brands/{id}/sending-identity/test":{"post":{"tags":["API v2"],"summary":"Send a test email with a brand's sending identity","description":"Sends one test email to your own account address and reports the From actually used. Scope `write`; owner / admin / editor of the brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key may only name its own brand (another brand → 403)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"},"from":{"type":"string","nullable":true},"via":{"type":"string","enum":["mailbox","resend"]},"reason":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"Refused (not an editor, bad input, domain not added); `error` says why"}}}},"/api/v2/ads/boost-candidates":{"get":{"tags":["API v2"],"summary":"Posts worth boosting","description":"The brand's published posts ranked for a boost: reach, engagement rate, link clicks recency and timeliness, weighted. Expired moments appear only in missedWindows; evergreen scores are unchanged. Left out: removed or archived posts, posts on networks a boost can't run on (listed with include=unboostable), and posts with no call to action (a destination link in the caption, a first comment or the CTA link; Flayr links do not count). Posts without metrics yet rank last with `noData: true`. Read-only: nothing is boosted or charged. Pro+ required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. Omitted: the key's brand (a brand-bound key) or the owner's active brand (required once the account is in more than one organization)."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"description":"How many days back to read (clamped)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"How many candidates to return (clamped)."},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["unboostable"]},"description":"Also list posts on networks a boost can't run on."}],"responses":{"200":{"description":"Ranked boost candidates","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"windowDays":{"type":"integer"},"truncated":{"type":"boolean","description":"More posts than one read covers; the ranking uses the newest."},"eligible":{"type":"integer","description":"Posts that passed every filter, before `limit`."},"excluded":{"type":"object","properties":{"removed":{"type":"integer"},"notBoostable":{"type":"integer"},"noCta":{"type":"integer"}}},"candidates":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string","description":"The Flayr post id (GET /api/v2/posts/{id})."},"network":{"type":"string","description":"facebook, instagram, tiktok, twitter (X), reddit, pinterest or linkedin."},"publishedAt":{"type":"number","description":"Epoch ms."},"caption":{"type":"string","description":"The caption, cut to 160 characters."},"metrics":{"type":"object","properties":{"reach":{"type":"integer","description":"max(impressions, views)."},"engagement":{"type":"integer"},"clicks":{"type":"integer"},"engagementRate":{"type":"number","nullable":true,"description":"engagement ÷ reach, in %."}}},"score":{"type":"number","nullable":true,"description":"0-100; null when the post has no data yet."},"noData":{"type":"boolean","description":"No metrics yet, or reach under the minimum: ranked after every scored post."},"parts":{"type":"object","nullable":true,"properties":{"views":{"type":"number","description":"Points this part adds to the score."},"engagementRate":{"type":"number","description":"Points this part adds to the score."},"linkClicks":{"type":"number","description":"Points this part adds to the score."},"recency":{"type":"number","description":"Points this part adds to the score."},"timeliness":{"type":"number","description":"Points this part adds to the score."}}},"cta":{"type":"object","properties":{"passed":{"type":"boolean"},"rule":{"type":"string","enum":["link"]},"link":{"type":"string","nullable":true,"description":"The destination link found (caption, first comment or CTA link)."}}},"adAccountConnected":{"type":"boolean","description":"An ad account that can boost on this network is selected for the brand."},"readiness":{"type":"string","enum":["not_connected","check"],"description":"`check`: connected; the live readiness checks run on /ads."},"boostEligible":{"type":"boolean"},"window":{"type":"string","enum":["now","upcoming","evergreen","closed"]},"windowLabel":{"type":"string","description":"Boost now, Upcoming: moment date, or Missed window: moment date."},"timeliness":{"type":"number","nullable":true,"minimum":0,"maximum":1,"description":"Null for neutral evergreen posts."},"moment":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"date":{"type":"string","format":"date"},"relevantFrom":{"type":"string","format":"date"},"validUntil":{"type":"string","format":"date"}}}}}},"missedWindows":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string","description":"The Flayr post id (GET /api/v2/posts/{id})."},"network":{"type":"string","description":"facebook, instagram, tiktok, twitter (X), reddit, pinterest or linkedin."},"publishedAt":{"type":"number","description":"Epoch ms."},"caption":{"type":"string","description":"The caption, cut to 160 characters."},"metrics":{"type":"object","properties":{"reach":{"type":"integer","description":"max(impressions, views)."},"engagement":{"type":"integer"},"clicks":{"type":"integer"},"engagementRate":{"type":"number","nullable":true,"description":"engagement ÷ reach, in %."}}},"score":{"type":"number","nullable":true,"description":"0-100; null when the post has no data yet."},"noData":{"type":"boolean","description":"No metrics yet, or reach under the minimum: ranked after every scored post."},"parts":{"type":"object","nullable":true,"properties":{"views":{"type":"number","description":"Points this part adds to the score."},"engagementRate":{"type":"number","description":"Points this part adds to the score."},"linkClicks":{"type":"number","description":"Points this part adds to the score."},"recency":{"type":"number","description":"Points this part adds to the score."},"timeliness":{"type":"number","description":"Points this part adds to the score."}}},"cta":{"type":"object","properties":{"passed":{"type":"boolean"},"rule":{"type":"string","enum":["link"]},"link":{"type":"string","nullable":true,"description":"The destination link found (caption, first comment or CTA link)."}}},"adAccountConnected":{"type":"boolean","description":"An ad account that can boost on this network is selected for the brand."},"readiness":{"type":"string","enum":["not_connected","check"],"description":"`check`: connected; the live readiness checks run on /ads."},"boostEligible":{"type":"boolean"},"window":{"type":"string","enum":["now","upcoming","evergreen","closed"]},"windowLabel":{"type":"string","description":"Boost now, Upcoming: moment date, or Missed window: moment date."},"timeliness":{"type":"number","nullable":true,"minimum":0,"maximum":1,"description":"Null for neutral evergreen posts."},"moment":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"date":{"type":"string","format":"date"},"relevantFrom":{"type":"string","format":"date"},"validUntil":{"type":"string","format":"date"}}}}},"description":"Expired seasonal posts, never boostable or ranked; score and parts are null."},"upcomingDates":{"type":"array","items":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"date":{"type":"string","format":"date"},"relevantFrom":{"type":"string","format":"date"},"validUntil":{"type":"string","format":"date"}}},"description":"Shared season config moments dated today or later (UTC)."},"unboostable":{"type":"array","description":"Only with include=unboostable.","items":{"type":"object","properties":{"postId":{"type":"string"},"network":{"type":"string"},"message":{"type":"string","example":"Can't boost on TikTok"}}}}}}}}},"400":{"description":"`days` or `limit` is not a whole number, or brandId is \"personal\"."},"402":{"description":"Pro+ required"},"403":{"description":"A brand-bound key asked for another brand."},"404":{"description":"Unknown brand, no brand scope for the key, or Ads is not enabled for the account."}}}},"/api/v2/ads/auto-judge":{"get":{"tags":["API v2"],"summary":"Auto-judge settings and proposed campaigns","description":"The brand's scheduled auto-judge: its settings and the recent proposal groups (one per run), each post with one call (boost, ad or let go), budget, window, season end, reason, stored prediction and whether it is over a cap. A missed-window post is only ever let go. Read-only: approving, rejecting and changing settings happen in the app (owner or admin); nothing is ever activated or charged from here. Pro+ required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. Omitted: the key's brand (a brand-bound key) or the owner's active brand (required once the account is in more than one organization)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":5},"description":"How many recent groups to return (clamped)."}],"responses":{"200":{"description":"Settings and proposal groups","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"settings":{"type":"object","properties":{"config":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Off by default; only the owner or an admin can switch it on, in the app."},"topN":{"type":"integer","description":"Boosts proposed per run."},"minScore":{"type":"integer","description":"Lowest score a boost may have."},"adTopN":{"type":"integer","description":"Draft PAUSED ads proposed per run."},"adMinScore":{"type":"integer"},"dailyBudgetMinor":{"type":"integer"},"boostDays":{"type":"integer","description":"Run length for evergreen boosts; seasonal runs end by the season end."},"adDays":{"type":"integer"},"minRunDays":{"type":"integer"},"expectedCpmMinor":{"type":"integer","description":"CPM used for the stored reach prediction."}}},"defaults":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Off by default; only the owner or an admin can switch it on, in the app."},"topN":{"type":"integer","description":"Boosts proposed per run."},"minScore":{"type":"integer","description":"Lowest score a boost may have."},"adTopN":{"type":"integer","description":"Draft PAUSED ads proposed per run."},"adMinScore":{"type":"integer"},"dailyBudgetMinor":{"type":"integer"},"boostDays":{"type":"integer","description":"Run length for evergreen boosts; seasonal runs end by the season end."},"adDays":{"type":"integer"},"minRunDays":{"type":"integer"},"expectedCpmMinor":{"type":"integer","description":"CPM used for the stored reach prediction."}}},"bounds":{"type":"object"},"lastRunAt":{"type":"number","nullable":true}}},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"number"},"status":{"type":"string","enum":["open","decided","expired"]},"proposedCount":{"type":"integer"},"letGoCount":{"type":"integer"},"decidedAt":{"type":"number","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"postId":{"type":"string"},"network":{"type":"string"},"caption":{"type":"string"},"intent":{"type":"string","enum":["boost","ad","let_go"]},"status":{"type":"string","enum":["proposed","approved","rejected","dropped","expired","let_go"]},"reason":{"type":"string","example":"3.1× median engagement; Black Friday ends 11/27"},"dailyBudgetMinor":{"type":"integer","nullable":true,"description":"Minor units of the ad account currency."},"days":{"type":"integer","nullable":true},"maxSpendMinor":{"type":"integer","nullable":true,"description":"Minor units of the ad account currency."},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true,"description":"Never after seasonEnd."},"seasonEnd":{"type":"string","format":"date","nullable":true,"description":"The season's validUntil; null for evergreen posts."},"seasonLabel":{"type":"string","nullable":true},"prediction":{"type":"object","nullable":true,"properties":{"expectedReach":{"type":"integer"},"expectedClicks":{"type":"integer"},"expectedCtr":{"type":"number"},"score":{"type":"number","nullable":true},"parts":{"type":"object","nullable":true},"cpmMinor":{"type":"integer"}}},"capsExceeded":{"type":"boolean","description":"Over the owner caps or the agent limits: can never be approved."},"capsReason":{"type":"string","nullable":true}}}}}}}}}}}},"400":{"description":"`limit` is not a whole number, or brandId is \"personal\"."},"402":{"description":"Pro+ required"},"403":{"description":"A brand-bound key asked for another brand."},"404":{"description":"Unknown brand, no brand scope for the key, or Ads is not enabled for the account."}}}},"/api/v2/ads/command-center/config":{"get":{"tags":["API v2"],"summary":"Ads command center config (flayr admin)","description":"flayr super-admins only. The businesses the Ads command center reports on (funnel steps, primary conversion, pinned ad accounts, analytics and revenue sources, enabled or not), the alert rules and the rollup window. A step whose source is not built or not connected yet reports \"not connected\", never 0. Read-only.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The effective config (the code defaults when nothing was saved)","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","description":"{ businesses, alertRules, weekStartsOn, rollupDays, rollupMaxSourceRowsPerAccountDay, rollupSettleDays, growthBusinessId }"},"isDefault":{"type":"boolean","description":"Nothing saved yet: these are the code defaults."},"updatedAt":{"type":"number","nullable":true,"description":"Epoch ms of the last save."},"updatedBy":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Not a flayr admin key"}}}},"/api/v2/ads/history-backfills":{"get":{"tags":["API v2"],"summary":"Meta history import status (flayr admin)","description":"flayr super-admins only. One entry per selected Meta ad account: the history import that brings in campaigns that ran before the account was connected (status, date range, progress, row counters), or null when none was started. A missing Meta permission is reported as `errorCode: MISSING_PERMISSION` with the exact scope in `missingScope`. Read-only: an import is started, resumed and cancelled on the super-admin page, and it never spends or edits a campaign.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The import status per selected Meta ad account","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"History import is switched on in the admin config."},"accounts":{"type":"array","items":{"type":"object","properties":{"adAccountRowId":{"type":"string"},"adAccountId":{"type":"string","description":"The Meta ad account id (act_...)."},"platform":{"type":"string"},"currency":{"type":"string"},"orgName":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"backfill":{"type":"object","nullable":true,"description":"{ backfillId, status (queued | running | paused | completed | failed | missing_permission | cancelled), fromDate, toDate, cursorEnd, phase, step, windowsDone, totalWindows, rowsWritten, rowsSkippedExisting, rowsSkippedUnreported, breakdownRows, entitiesCreated, creativesWritten, errorCode, missingScope, errorDetail, lastUsagePct, nextRunAt, updatedAt, finishedAt }. null when no import was started for the account."}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Not a flayr admin key"}}}},"/api/v2/ads/launch-review":{"get":{"tags":["API v2"],"summary":"Paused campaigns ready for review","description":"Every paused campaign of the brand, on every network, with a preview of each ad and the pre-launch checks: the destination resolves, UTM tags, a button where the network has one, an end date or lifetime budget, the max spend, the call to action and the same destination across networks. Each check is pass, warn or fail with a plain line. Read-only: it never switches a campaign on, changes a budget or spends. Switching on stays with the account owner or an admin in the app. Needs a key with `read`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. Omitted: the key's brand (a brand-bound key) or the owner's active brand (required once the account is in more than one organization)."}],"responses":{"200":{"description":"The launch review","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Every paused campaign, before the list cap."},"items":{"type":"array","items":{"type":"object","properties":{"campaign":{"type":"object","description":"The campaign as GET /api/v2/ads/campaigns/{id} returns it, without ad sets, plus `adCount`.","additionalProperties":true},"ads":{"type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Flayr's ad id, once the ad has synced."},"status":{"type":"string","nullable":true},"mediaUrl":{"type":"string","nullable":true,"description":"Image or video thumbnail (https)."},"isVideo":{"type":"boolean"},"primaryText":{"type":"string","nullable":true},"headline":{"type":"string","nullable":true},"button":{"type":"string","nullable":true,"description":"The call-to-action button, e.g. SHOP_NOW."},"destinationHost":{"type":"string","nullable":true}}},"description":"Null when the network could not be read right now."},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["destination","utm","button","bounded_spend","max_spend","cta","parity"]},"status":{"type":"string","enum":["pass","warn","fail"]},"message":{"type":"string","description":"One plain line."}}}},"overall":{"type":"string","enum":["pass","warn","fail"]},"canSwitchOn":{"type":"boolean","description":"False until the campaign has an end date or a lifetime budget."},"switchOnBlockedReason":{"type":"string","nullable":true,"example":"Set an end date or lifetime budget first."},"hasPlatformPreview":{"type":"boolean","description":"The network renders its own ad preview in the app."}}}}}}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The key lacks `read`, a brand-bound key asked for another brand, or Ads is not enabled for the account."},"404":{"description":"Unknown brand."},"500":{"description":"The review could not be loaded right now."}}}},"/api/v2/ads/boosts":{"post":{"tags":["API v2"],"summary":"Boost a published X post (paused, proposed)","security":[{"bearerAuth":[]}],"description":"platform twitter (or x): promotes a post the brand has already published on X, as published, through the brand's selected X Ads account. The boost is created PAUSED and lands in the owner's Proposed campaigns; nothing runs or spends until the owner approves it (`/api/v2/ads/campaigns/{id}/approve` with `activate: true`). Pass postId (a flayr post id) or contentId (a Library item id) of a post published on X, goal, a whole-dollar daily budget at or above the X daily minimum, and an end (endDate or durationDays). The exposure (daily x days) must fit the owner's caps. ctaOverride, budgetUsd, targeting, placements and the other Meta/TikTok fields are refused. Answers 403 NETWORK_BOOST_DISABLED until the owner has switched X boosts on (Ads > Spend controls > Networks); 409 ADS_ACCOUNT_REQUIRED when no X Ads account is selected; other platforms answer 400 PLATFORM_NOT_SUPPORTED (boost those in the dashboard). Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","platform","budget","countries"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"platform":{"type":"string","enum":["twitter","x"],"description":"Only X boosts are open to a brand key."},"postId":{"type":"string","description":"The flayr post id (GET /api/v2/posts, or ads boost candidates). One of postId or contentId."},"contentId":{"type":"string","description":"A Library item id whose post went out on X. One of postId or contentId."},"goal":{"type":"string","enum":["engagement","traffic","awareness","video_views"],"description":"As the owner's X goal options allow (default: the owner's X default goal); video_views needs a video post."},"budget":{"type":"number","description":"Whole dollars per day, at or above the X daily minimum."},"budgetType":{"type":"string","enum":["daily"],"description":"X boosts take a daily budget only."},"startDate":{"type":"string","description":"ISO date or date-time; default now."},"endDate":{"type":"string","description":"ISO date or date-time; required unless durationDays is given."},"durationDays":{"type":"integer","description":"Whole days, at least 1; instead of endDate."},"countries":{"type":"array","items":{"type":"string"},"description":"Required: ISO alpha-2 country codes, e.g. [\"US\"]."},"idempotencyKey":{"type":"string","description":"Optional; repeats with the same key return the first result instead of boosting twice."}}}}}},"responses":{"200":{"description":"Paused boost created, or an idempotent replay","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","description":"Flayr campaign id; use it with campaign read-back, launch review and approve."},"zernioCampaignId":{"type":"string"},"platformCampaignId":{"type":"string","nullable":true,"description":"The X campaign id, when returned."},"status":{"type":"string","description":"paused: nothing runs or spends until the owner approves it."},"goal":{"type":"string"},"maxSpendMinor":{"type":"integer","description":"The most the boost can spend (daily budget x days), in cents."},"days":{"type":"integer"},"persisted":{"type":"boolean"},"approvalStatus":{"type":"string","enum":["proposed"]},"actionId":{"type":"string"},"replayed":{"type":"boolean"}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/audiences":{"get":{"tags":["API v2"],"summary":"List custom and lookalike audiences","security":[{"bearerAuth":[]}],"description":"The brand's Meta custom and lookalike audiences (flayr ids), and the owner's audience limits (presets on, most included / excluded per ad set, lookalike ratio range, batch size). Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"responses":{"200":{"description":"Audiences","content":{"application/json":{"schema":{"type":"object","properties":{"audiences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The flayr audience id: use it in includeAudienceIds / excludeAudienceIds and as seedAudienceId."},"name":{"type":"string"},"type":{"type":"string","enum":["website","customer_list","lookalike","engagement"]},"preset":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"size":{"type":"integer","nullable":true},"platformAudienceId":{"type":"string","nullable":true,"description":"The Meta custom audience id, once known."}}}},"limits":{"type":"object"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED)"}}},"post":{"tags":["API v2"],"summary":"Create a custom or lookalike audience","security":[{"bearerAuth":[]}],"description":"Creates a Meta custom audience on the brand's selected ad account from a preset: site_visitors (everyone the brand's Meta pixel saw), signup_page_visitors (pixel visits to URLs containing the configured sign-up path, or urlContains), trial_starters (people who fired the configured trial event, StartTrial by default), customer_list (an empty list; fill it with POST /api/v2/ads/audiences/{audienceId}/users) or lookalike (seedAudienceId, a 2-letter country and a ratio). Website presets need the brand's Meta pixel (409 ADS_NO_META_PIXEL). Which presets are on, the retention window and the lookalike ratio range are the owner's ads config (403 AUDIENCE_PRESET_DISABLED, 403 AUDIENCES_DISABLED). An audience never spends. Answers 201 with the audience. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","preset"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"preset":{"type":"string","enum":["site_visitors","signup_page_visitors","trial_starters","customer_list","lookalike"]},"name":{"type":"string","description":"Up to 100 characters; default: the preset name."},"description":{"type":"string","description":"Up to 500 characters."},"retentionDays":{"type":"integer","description":"Website presets: how many days back the audience reaches (1 to the configured max, Meta max 180)."},"urlContains":{"type":"string","description":"signup_page_visitors only: the URL part that marks the sign-up page; default from the ads config."},"seedAudienceId":{"type":"string","description":"lookalike only, required: a flayr audience id in this brand (not a lookalike)."},"country":{"type":"string","description":"lookalike only, required: 2-letter country code."},"ratio":{"type":"number","description":"lookalike only: the share of the country's people, inside the configured range (default the minimum, 0.01 = 1%)."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"201":{"description":"Audience created","content":{"application/json":{"schema":{"type":"object","properties":{"audience":{"type":"object","properties":{"id":{"type":"string","description":"The flayr audience id: use it in includeAudienceIds / excludeAudienceIds and as seedAudienceId."},"name":{"type":"string"},"type":{"type":"string","enum":["website","customer_list","lookalike","engagement"]},"preset":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"size":{"type":"integer","nullable":true},"platformAudienceId":{"type":"string","nullable":true,"description":"The Meta custom audience id, once known."}}},"actionId":{"type":"string"}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/audiences/{audienceId}/users":{"post":{"tags":["API v2"],"summary":"Upload a customer list","security":[{"bearerAuth":[]}],"description":"Adds people to a customer_list audience: users is a list of { email?, phone? } (phones with the country code). Values are normalised (trimmed, lower-cased, phone digits only) and deduplicated; already-hashed SHA-256 values pass through. Rows without a valid email or phone are skipped and counted. At most the configured batch size per call (Meta max 10,000). flayr never stores or logs the people sent: the audit keeps counts and a digest. 400 AUDIENCE_NOT_CUSTOMER_LIST for any other audience type. Needs the explicit `ads:manage` scope.","parameters":[{"name":"audienceId","in":"path","required":true,"schema":{"type":"string"},"description":"A flayr audience id (GET /api/v2/ads/audiences)."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","users"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"users":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"audienceId":{"type":"string"},"sent":{"type":"integer"},"skipped":{"type":"integer"},"received":{"type":"integer","nullable":true},"invalid":{"type":"integer","nullable":true},"actionId":{"type":"string"}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/site-tags":{"get":{"tags":["API v2"],"summary":"Read the site ad tags","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"flayr.social's ad tags per network (reddit, tiktok, linkedin, x, google, pinterest, snapchat) and the Meta pixel: the saved id, the FLAYR_TAG_* env default, whether it is requested and whether it is effectively on (requested + consent recorded + a valid id). Read-only. The tags load on flayr.social for every visitor, so `ads:manage` is not enough on its own: the key's owner must be a flayr super-admin, or its brand must be listed in the Convex env var FLAYR_SITE_TAG_BRAND_IDS (else 403 `ADS_SITE_TAG_NOT_ALLOWED`). Needs the explicit `ads:manage` scope.","responses":{"200":{"description":"The site tags","content":{"application/json":{"schema":{"type":"object","properties":{"consentApproved":{"type":"boolean"},"respectGlobalPrivacyControl":{"type":"boolean"},"meta":{"type":"object"},"networks":{"type":"array","items":{"type":"object"}},"authority":{"type":"string","enum":["super_admin","allowlisted_brand"]}}}}}},"400":{"description":"Invalid body, agentName / reason missing, or the tag is invalid (code ADS_SITE_TAG_INVALID, audited)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing ads:manage (SCOPE_REQUIRED), ADS_SITE_TAG_NOT_ALLOWED, not owner/admin, or the kill switch is on"}}},"post":{"tags":["API v2"],"summary":"Set one network's site ad tag","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"Sets ONE network's tag on flayr.social. Fields left out keep their saved value; an empty string clears a field; `enabled` left out keeps the saved switch. Same validation as the super-admin form: a tag turns on only after the consent decision is recorded, and ids must be in the network's format. Audited in Ads > Agent activity (action set_site_tag), refusals included. Spends nothing. The tags load on flayr.social for every visitor, so `ads:manage` is not enough on its own: the key's owner must be a flayr super-admin, or its brand must be listed in the Convex env var FLAYR_SITE_TAG_BRAND_IDS (else 403 `ADS_SITE_TAG_NOT_ALLOWED`). Needs the explicit `ads:manage` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","network"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"network":{"type":"string","enum":["reddit","tiktok","linkedin","x","google","pinterest","snapchat"]},"id":{"type":"string","description":"The tag id the site loads (TikTok: the pixel code)."},"enabled":{"type":"boolean"},"signupConversionId":{"type":"string","description":"The network's sign-up conversion reference, where it has one."},"leadConversionId":{"type":"string","description":"X and Google only."},"trialConversionId":{"type":"string","description":"X and Google only."},"pageViewConversionId":{"type":"string","description":"X and Google only: the page view conversion reference."},"contentViewConversionId":{"type":"string","description":"X and Google only: the content view conversion reference."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Owner approval requested","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid body, agentName / reason missing, or the tag is invalid (code ADS_SITE_TAG_INVALID, audited)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing ads:manage (SCOPE_REQUIRED), ADS_SITE_TAG_NOT_ALLOWED, not owner/admin, or the kill switch is on"}}}},"/api/v2/ads/site-tags/tiktok/pixel":{"get":{"tags":["API v2"],"summary":"List the TikTok pixels","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"The TikTok pixels on the brand's selected TikTok ad account. Read-only. Needs the explicit `ads:manage` scope.","responses":{"200":{"description":"The pixels","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"pixels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"TikTok's numeric pixel id (campaign optimization, promotedObject.pixelId)."},"siteTagId":{"type":"string","nullable":true,"description":"The pixel code the site loads (networks.tiktok.id)."},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive","unavailable"]},"lastFiredTime":{"type":"number","nullable":true,"description":"Unix seconds of the last event, or null if it never fired."},"reused":{"type":"boolean"}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing ads:manage (SCOPE_REQUIRED), ADS_SITE_TAG_NOT_ALLOWED, not owner/admin, or the kill switch is on"},"409":{"description":"No TikTok ad account selected (ADS_NO_AD_ACCOUNT)"},"502":{"description":"Could not read the pixels"}}},"post":{"tags":["API v2"],"summary":"Find or create the TikTok pixel and save it as the site tag","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"Lists the TikTok pixels on the brand's selected TikTok ad account and reuses the one named `name` (default \"flayr.social\") or the one `tagId` names. Only when none matches does it create one (Zernio's create is not idempotent; audited as create_tracking_tag; a real pixel on the real ad account from any environment; a pixel costs nothing). Then, unless `save` is false, it saves the pixel code as the site's TikTok tag (the same audited write as POST /api/v2/ads/site-tags); `enable` turns it on, left out keeps the saved switch. 201 created, 200 reused. A failed create answers 502 with `manualStep`, the TikTok Ads Manager steps to create it by hand. The tags load on flayr.social for every visitor, so `ads:manage` is not enough on its own: the key's owner must be a flayr super-admin, or its brand must be listed in the Convex env var FLAYR_SITE_TAG_BRAND_IDS (else 403 `ADS_SITE_TAG_NOT_ALLOWED`). Needs the explicit `ads:manage` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"name":{"type":"string","description":"Default \"flayr.social\"."},"tagId":{"type":"string","description":"Reuse this existing pixel (numeric id or pixel code)."},"save":{"type":"boolean","description":"Default true: save the pixel code as networks.tiktok.id."},"enable":{"type":"boolean","description":"Turn the TikTok tag on (needs the consent decision recorded)."}}}}}},"responses":{"200":{"description":"Reused an existing pixel","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"pixel":{"type":"object","properties":{"id":{"type":"string","description":"TikTok's numeric pixel id (campaign optimization, promotedObject.pixelId)."},"siteTagId":{"type":"string","nullable":true,"description":"The pixel code the site loads (networks.tiktok.id)."},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive","unavailable"]},"lastFiredTime":{"type":"number","nullable":true,"description":"Unix seconds of the last event, or null if it never fired."},"reused":{"type":"boolean"}}},"saved":{"type":"object","nullable":true}}}}}},"201":{"description":"Created the pixel","content":{"application/json":{"schema":{"type":"object","properties":{"adAccountId":{"type":"string"},"pixel":{"type":"object","properties":{"id":{"type":"string","description":"TikTok's numeric pixel id (campaign optimization, promotedObject.pixelId)."},"siteTagId":{"type":"string","nullable":true,"description":"The pixel code the site loads (networks.tiktok.id)."},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive","unavailable"]},"lastFiredTime":{"type":"number","nullable":true,"description":"Unix seconds of the last event, or null if it never fired."},"reused":{"type":"boolean"}}},"saved":{"type":"object","nullable":true}}}}}},"400":{"description":"Invalid body, agentName / reason missing, or the tag is invalid (code ADS_SITE_TAG_INVALID, audited)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing ads:manage (SCOPE_REQUIRED), ADS_SITE_TAG_NOT_ALLOWED, not owner/admin, or the kill switch is on"},"409":{"description":"No TikTok ad account selected, tagId not on the ad account, or more than one pixel with that name"},"502":{"description":"Zernio could not list or create the pixel, or returned no pixel code (manualStep has the steps)"}}}},"/api/v2/ads/page":{"get":{"tags":["API v2"],"summary":"Read the brand's ads Page","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"The Facebook Page the brand's Meta ads run as (the owner-picked Page), whether it is still connected and active, and the candidates: the brand's own connected Facebook accounts. Every Meta create (traffic, conversions, lead, messages, boost) runs as the picked Page when one is set. Read-only. Scope `read` or any `ads:*` scope.","responses":{"200":{"description":"The pick and the candidates","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object","nullable":true,"properties":{"pageId":{"type":"string"},"name":{"type":"string","nullable":true},"handle":{"type":"string","nullable":true},"accountId":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","needs_reconnect","not_connected"],"description":"active: connected and usable. needs_reconnect: the owner must reconnect it. not_connected: no longer among the brand's Facebook accounts."},"setVia":{"type":"string","enum":["api","dashboard"]},"setAt":{"type":"string","format":"date-time"}}},"candidates":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"The Meta Page id."},"accountId":{"type":"string","description":"The connected Facebook account id."},"name":{"type":"string"},"handle":{"type":"string"},"isActive":{"type":"boolean"},"needsReconnection":{"type":"boolean"},"status":{"type":"string","enum":["active","needs_reconnect","not_connected"],"description":"active: connected and usable. needs_reconnect: the owner must reconnect it. not_connected: no longer among the brand's Facebook accounts."}}}},"hasProfile":{"type":"boolean","description":"False when the brand has no social profile yet (no candidates)."}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Insufficient scope, or ads not enabled for the account"}}},"put":{"tags":["API v2"],"summary":"Set the brand's ads Page","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"Picks the Facebook Page the brand's Meta ads run as, from the brand's ALREADY connected Facebook accounts (GET /api/v2/ads/page lists them); `pageId: null` clears the pick. An agent can never connect an account: connecting a Page is the owner's step in Connections. Owner/admin only, kill switch respected, audited in Ads > Agent activity (action set_ads_page), refusals included. Spends nothing and writes nothing to the ad network. Needs the explicit `ads:manage` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","pageId"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"pageId":{"type":"string","nullable":true,"description":"A connected Page's Meta Page id (or its Facebook account id); null clears the pick."}}}}}},"responses":{"200":{"description":"Set","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied"]},"actionId":{"type":"string"},"page":{"type":"object","properties":{"pageId":{"type":"string","description":"The Meta Page id."},"accountId":{"type":"string","description":"The connected Facebook account id."},"name":{"type":"string"},"handle":{"type":"string"},"isActive":{"type":"boolean"},"needsReconnection":{"type":"boolean"},"status":{"type":"string","enum":["active","needs_reconnect","not_connected"],"description":"active: connected and usable. needs_reconnect: the owner must reconnect it. not_connected: no longer among the brand's Facebook accounts."}},"nullable":true},"previous":{"type":"object","nullable":true,"properties":{"pageId":{"type":"string"},"name":{"type":"string","nullable":true}}}}}}}},"202":{"description":"approval_requested (the owner must approve)"},"400":{"description":"Invalid body, agentName / reason missing, or ADS_PAGE_NOT_CONNECTED (the Page is not one of the brand's connected Facebook accounts; the body lists `candidates`)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing ads:manage (SCOPE_REQUIRED), not owner/admin, or the kill switch is on"},"409":{"description":"ADS_PAGE_INACTIVE: the Page must be reconnected by the owner first"},"502":{"description":"ADS_PAGE_LOOKUP_FAILED: the connected accounts could not be read"}}}},"/api/v2/ads/layout":{"get":{"tags":["API v2"],"summary":"The Ads page layout","description":"The /ads page's tabs (Insights, Campaigns, Ads, Leads, Setup, Pending, Custom) in order, each with its sections, who sees each section, and the API v2 path and MCP tool that return the same data. Deep-link a tab with /ads?tab=<value>. Read-only. Scope `read` or any `ads:*` scope.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Tabs and sections","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","example":"/ads"},"tabParam":{"type":"string","example":"tab"},"defaultTab":{"type":"string","enum":["insights","campaigns","ads","leads","setup","pending","custom"]},"tabs":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","enum":["insights","campaigns","ads","leads","setup","pending","custom"]},"label":{"type":"string"},"summary":{"type":"string"},"url":{"type":"string","example":"/ads?tab=setup"},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"spend-controls"},"label":{"type":"string"},"access":{"type":"string","enum":["boost","manage"],"description":"boost: Pro and up. manage: Premium and up."},"mode":{"type":"string","enum":["basic","advanced"],"description":"advanced: shown only when the nav is in Advanced mode."},"api":{"type":"string","nullable":true,"description":"The API v2 path that returns this section's data, when one exists."},"mcpTool":{"type":"string","nullable":true,"description":"The MCP tool that returns this section's data, when one exists."}}}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Insufficient scope, or ads are not on the plan"}}}},"/api/v2/ads/lead-replies":{"get":{"tags":["API v2"],"summary":"Lead response rule (messaging-ad leads)","description":"The brand's lead response rule: whether a person who types to its click-to-message ad gets an automatic first reply in the same DM thread, the text, the platform window, and the recent leads with when they were answered. Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands, or `personal`. Omitted: the key's brand (a brand-bound key) or the owner's active brand."}],"responses":{"200":{"description":"The rule","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"channel":{"type":"string","enum":["dm"],"description":"Where the reply is sent. Only the same DM thread (Messenger, Instagram Direct) today; SMS and WhatsApp are later slices."},"firstReplyEnabled":{"type":"boolean","description":"Off by default."},"firstReplyText":{"type":"string","nullable":true,"description":"`{{name}}` becomes the first name. Null: the greeting is sent."},"greeting":{"type":"string","description":"The welcome greeting of the brand's messaging ads."},"windowHours":{"type":"object","additionalProperties":{"type":"number"},"example":{"facebook":24,"instagram":24},"description":"Per platform, the messaging window in hours: no reply is sent once it has closed."},"recentLeads":{"type":"array","description":"Up to 20 recent messaging-ad leads (no message text).","items":{"type":"object","properties":{"conversationId":{"type":"string"},"platform":{"type":"string"},"adName":{"type":"string","nullable":true},"firstMessageAt":{"type":"number"},"firstReplyAt":{"type":"number","nullable":true,"description":"When the automatic first reply was claimed."},"autoReplySentAt":{"type":"number","nullable":true},"ownerFirstReplyAt":{"type":"number","nullable":true},"responseMs":{"type":"number","nullable":true}}}}}}}}},"403":{"description":"Ads is not enabled for the account, or a brand-bound key asked for another brand."},"404":{"description":"Unknown brand."}}},"post":{"tags":["API v2"],"summary":"Set the lead response rule","description":"Switches the automatic first reply on or off and sets its text. Needs the `ads:manage` scope and an owner or admin of the brand's organization. Each new messaging-ad conversation gets the reply once, only while the platform window is open; quick-reply taps keep their own answer. DM replies are free: nothing is charged.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands, or `personal`. Omitted: the key's brand (a brand-bound key) or the owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["firstReplyEnabled"],"properties":{"firstReplyEnabled":{"type":"boolean"},"firstReplyText":{"type":"string","nullable":true,"maxLength":600,"description":"Omitted: keep the stored text. Null or empty: use the greeting."}}}}}},"responses":{"200":{"description":"The saved rule","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"channel":{"type":"string","enum":["dm"],"description":"Where the reply is sent. Only the same DM thread (Messenger, Instagram Direct) today; SMS and WhatsApp are later slices."},"firstReplyEnabled":{"type":"boolean","description":"Off by default."},"firstReplyText":{"type":"string","nullable":true,"description":"`{{name}}` becomes the first name. Null: the greeting is sent."},"greeting":{"type":"string","description":"The welcome greeting of the brand's messaging ads."},"windowHours":{"type":"object","additionalProperties":{"type":"number"},"example":{"facebook":24,"instagram":24},"description":"Per platform, the messaging window in hours: no reply is sent once it has closed."},"recentLeads":{"type":"array","description":"Up to 20 recent messaging-ad leads (no message text).","items":{"type":"object","properties":{"conversationId":{"type":"string"},"platform":{"type":"string"},"adName":{"type":"string","nullable":true},"firstMessageAt":{"type":"number"},"firstReplyAt":{"type":"number","nullable":true,"description":"When the automatic first reply was claimed."},"autoReplySentAt":{"type":"number","nullable":true},"ownerFirstReplyAt":{"type":"number","nullable":true},"responseMs":{"type":"number","nullable":true}}}}}}}}},"400":{"description":"Invalid body."},"403":{"description":"Missing ads:manage, Ads not enabled, or the caller is not an owner/admin of the brand."},"404":{"description":"Unknown brand."}}}},"/api/v2/ads/lead-forms/consent":{"get":{"tags":["API v2"],"summary":"Get lead consent and follow-up settings","security":[{"bearerAuth":[]}],"description":"The brand's saved lead consent, the store and follow-up switches, the defaults, and the forms created with the consent checkbox. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","properties":{"consent":{"type":"object","properties":{"text":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"checkboxLabel":{"type":"string","nullable":true}},"description":"The saved consent; null fields are unsaved."},"enabled":{"type":"boolean","description":"Leads from the brand's forms are stored."},"followUpEnabled":{"type":"boolean","description":"Stored leads who ticked consent get the follow-up email."},"saved":{"type":"boolean","description":"Consent text and version are saved."},"defaults":{"type":"object","properties":{"text":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"checkboxLabel":{"type":"string","nullable":true}},"description":"The code defaults (v1 wording)."},"consentForms":{"type":"array","items":{"type":"object","properties":{"formId":{"type":"string"},"consentVersion":{"type":"string"},"copiedFromFormId":{"type":"string"},"createdAt":{"type":"number"}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), or the key cannot manage this brand (code ADS_NOT_OWNER)"}}},"post":{"tags":["API v2"],"summary":"Save lead consent and follow-up settings","security":[{"bearerAuth":[]}],"description":"Saves the brand's lead consent and switches. Every field left out keeps its saved value, then the default; `enabled` and `followUpEnabled` left out keep the saved switch. New wording needs a new consentVersion. `followUpEnabled` needs `enabled`, and emails real leads who ticked consent. Answers the GET shape plus `ok`. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"consentText":{"type":"string","description":"1-1000 characters."},"consentVersion":{"type":"string","description":"1-40 characters; change it whenever the wording changes."},"consentTitle":{"type":"string","description":"1-60 characters."},"consentCheckboxLabel":{"type":"string","description":"1-200 characters."},"enabled":{"type":"boolean"},"followUpEnabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/lead-forms/consent-copy":{"post":{"tags":["API v2"],"summary":"Copy an Instant Form with the consent checkbox","security":[{"bearerAuth":[]}],"description":"Copies a live Meta Instant Form into a new form with the same questions, pages and privacy link, plus the brand's saved consent checkbox. Meta forms cannot be edited, so this is how an ad gains consent. One vendor call, never retried. 400 CONSENT_NOT_SAVED until the consent is saved. Answers `{ ok, formId, name, copiedFromFormId, consentVersion, actionId }`. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","copyFromFormId"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"copyFromFormId":{"type":"string","description":"The live Meta form id (digits)."},"name":{"type":"string","description":"Optional new form name."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/lead-forms/swap-ad":{"post":{"tags":["API v2"],"summary":"Point a live lead ad at another Instant Form","security":[{"bearerAuth":[]}],"description":"Creates a new ad PAUSED in the same ad set with the same copy and media and `newFormId`, switches it on, and only then pauses the old ad. Answers `{ ok, oldAdId, newAdId, newFormId, adSetId, oldAdPaused, actionId }`. A failed step answers 502 with `step` (create, resume or pause) and what still serves. Single-image and single-video ads only; 409 ALREADY_ON_FORM when the ad already uses the form. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","adId","newFormId"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"adId":{"type":"string","description":"The live Meta ad id (digits)."},"newFormId":{"type":"string","description":"The Instant Form the new ad uses (digits)."},"name":{"type":"string","description":"Optional new ad name; default \"<old name> (form <id>)\"."},"idempotencyKey":{"type":"string","description":"Optional; 1-255 characters of A-Z a-z 0-9 . _ : -. Makes a retry of the create safe."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/brand/intelligence":{"get":{"tags":["API v2"],"summary":"Get a brand's Brand Intelligence","description":"The brand profile (identity, audience, values, pillars, hashtag sets, colors, fonts) and its default voice. Membership in the brand's org is enough.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands. A brand-bound key is pinned to its own brand (may be omitted; another brand → 403); an account-wide key must name one."}],"responses":{"200":{"description":"Brand Intelligence","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"brandName":{"type":"string"},"profile":{"type":"object","nullable":true,"description":"The stored profile, incl. primaryColor, secondaryColor, colors[] and fonts[]."},"voice":{"type":"object","nullable":true},"colors":{"type":"object","nullable":true,"properties":{"primary":{"type":"string"},"secondary":{"type":"string","nullable":true},"palette":{"type":"array","items":{"type":"string"}}},"description":"The brand look in the PATCH shape; `palette` is the full ordered list. null when no colors are set."},"fonts":{"type":"object","nullable":true,"properties":{"heading":{"type":"string"},"body":{"type":"string"}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"A brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member"},"422":{"description":"No brandId for an account-wide key, or \"personal\""}}},"patch":{"tags":["API v2"],"summary":"Update a brand's Brand Intelligence, colors and fonts","description":"Sets profile and/or voice fields, the brand colors and the brand fonts. Requires the write (or admin) scope and owner / admin / editor in the brand's org. Each change is recorded in the org audit log against the API key.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Send at least one of profile, voice, colors, fonts.","properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. A brand-bound key is pinned to its own brand (may be omitted; another brand → 403); an account-wide key must name one."},"profile":{"type":"object","description":"Only the fields sent are changed. Unknown fields are a 422.","properties":{"companyName":{"type":"string","maxLength":200},"tagline":{"type":"string","maxLength":200},"mission":{"type":"string","maxLength":4000},"industry":{"type":"string","maxLength":200},"website":{"type":"string","maxLength":200},"competitors":{"type":"array","items":{"type":"string"}},"brandValues":{"type":"array","items":{"type":"string"}},"contentPillars":{"type":"array","items":{"type":"string"}},"targetDemographics":{"type":"object","properties":{"ageRanges":{"type":"array","items":{"type":"string"}},"gender":{"type":"string"},"location":{"type":"array","items":{"type":"string"}},"interests":{"type":"array","items":{"type":"string"}},"painPoints":{"type":"array","items":{"type":"string"}}}},"hashtagSets":{"type":"array","maxItems":20,"items":{"type":"object","required":["name","tags"],"properties":{"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"voice":{"type":"object","description":"The brand default voice. Created (as the default) when the brand has none.","properties":{"name":{"type":"string"},"tone":{"type":"string"},"style":{"type":"string"},"targetAudience":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"avoidWords":{"type":"array","items":{"type":"string"}},"sampleContent":{"type":"string"},"examplePosts":{"type":"array","items":{"type":"string"}},"exampleLinks":{"type":"array","items":{"type":"string"}},"guide":{"type":"string","maxLength":30000}}},"colors":{"type":"object","required":["primary"],"description":"REPLACES the brand palette, the same as saving Brand → Overview → Brand Colors: the stored list is primary, secondary, then palette (duplicates dropped); primary and secondary are its top two. 6-digit hex, `#` optional, stored lower case.","properties":{"primary":{"type":"string","pattern":"^#?[0-9a-fA-F]{6}$","example":"#ff6b00"},"secondary":{"type":"string","pattern":"^#?[0-9a-fA-F]{6}$","example":"#ff6b00"},"palette":{"type":"array","maxItems":16,"items":{"type":"string","pattern":"^#?[0-9a-fA-F]{6}$","example":"#ff6b00"},"description":"Further brand colors, in order."}}},"fonts":{"type":"object","description":"Font family names. A role left out keeps its stored font. At least one is required.","properties":{"heading":{"type":"string","maxLength":100,"example":"Inter"},"body":{"type":"string","maxLength":100,"example":"Inter"}}}}},"example":{"brandId":"wd76fnmzh8p9v3k49278kw6qh18f2g9y","colors":{"primary":"#ff6b00","secondary":"#1a1a1a","palette":["#d56c28","#c05000","#0a0a0a","#e1ded9"]},"fonts":{"heading":"Inter","body":"Inter"}}}}},"responses":{"200":{"description":"Updated; same shape as GET plus voiceCreated","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"brandName":{"type":"string"},"profile":{"type":"object","nullable":true,"description":"The stored profile, incl. primaryColor, secondaryColor, colors[] and fonts[]."},"voice":{"type":"object","nullable":true},"colors":{"type":"object","nullable":true,"properties":{"primary":{"type":"string"},"secondary":{"type":"string","nullable":true},"palette":{"type":"array","items":{"type":"string"}}},"description":"The brand look in the PATCH shape; `palette` is the full ordered list. null when no colors are set."},"fonts":{"type":"object","nullable":true,"properties":{"heading":{"type":"string"},"body":{"type":"string"}}},"voiceCreated":{"type":"boolean"}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing write scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or the key owner cannot edit it"},"422":{"description":"Unknown field, bad hex color, bad font name, or too many items"}}}},"/api/v2/accounts":{"get":{"tags":["API v2"],"summary":"List connected social accounts","description":"The social accounts POST /api/v2/publish with the same brandId would post through: platform, handle, display name, health, whether it is the brand's default for its platform (isDefault) and whether flayr can post there now (postable; Reddit is paused). A brand-bound key can only list its own brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."}],"responses":{"200":{"description":"Connected accounts","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string"},"handle":{"type":"string","nullable":true},"displayName":{"type":"string","nullable":true},"health":{"type":"string","enum":["healthy","needs_reauth","disconnected"]},"postable":{"type":"boolean"},"pausedReason":{"type":"string"},"sharedFrom":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"brandName":{"type":"string"}}},"isDefault":{"type":"boolean","description":"The brand's default destination for this platform (set it with PUT /api/v2/accounts/defaults)."}}}}}}}}},"400":{"description":"The brand has no connected Zernio profile"},"401":{"description":"Unauthorized"},"403":{"description":"A brand-bound key asking for another brand"},"404":{"description":"Unknown brandId"},"429":{"description":"Rate or quota limit"},"502":{"description":"Zernio could not be reached"}}}},"/api/v2/accounts/{id}":{"delete":{"tags":["API v2"],"summary":"Remove one dead connection","description":"Removes ONE connection by account id from the brand, for a dead connection that a platform-wide disconnect cannot reach without also taking the brand's healthy accounts on that platform. Never cancels anything: while a scheduled post, a held post, a post waiting for review, a booked queue item or an active share is still pinned to the account, it refuses with 409 and the counts. An account still connected and healthy is refused too (disconnect it on the Connect page). Pass dryRun=true to see the counts without removing anything. Nothing is changed at the social network. Needs the write scope and a brand owner or admin.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An account id (as GET /api/v2/accounts shows), or the connection row id when several connections carry the same account id."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"The brand the connection belongs to, as for GET /api/v2/accounts."},{"name":"dryRun","in":"query","required":false,"schema":{"type":"boolean"},"description":"true → only report what is pinned and whether it could be removed; nothing is written."}],"responses":{"200":{"description":"Removed (or, with dryRun, removable)","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"},"dryRun":{"type":"boolean"},"removable":{"type":"boolean"},"accountId":{"type":"string","nullable":true},"rowId":{"type":"string"},"platform":{"type":"string"},"handle":{"type":"string","nullable":true},"connectionHealth":{"type":"string","nullable":true},"counts":{"type":"object","properties":{"scheduled":{"type":"integer"},"held":{"type":"integer"},"pendingReview":{"type":"integer"},"queueItems":{"type":"integer"},"activeShares":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the write scope, the caller is not a brand owner or admin, or a brand-bound key asking for another brand"},"404":{"description":"No connection with that id in this brand"},"409":{"description":"Refused, nothing removed. code: pinned (counts says what is booked on it), still_connected (healthy; use the Connect page), ambiguous (rowIds: remove one by its row id), truncated (too much to check safely)"},"429":{"description":"Rate or quota limit"},"502":{"description":"The live connection could not be checked, or the removal failed; retry"}}}},"/api/v2/accounts/{id}/refresh":{"post":{"tags":["API v2"],"summary":"Refresh a connected account's profile","description":"Re-reads the account's handle, display name and avatar from the network and stores them, so a renamed account shows its new name. Changes nothing else. status: updated (the new values are returned), unchanged, or unavailable (could not read it now). When it is not updated, reconnectUrl is where the user reconnects the account, which re-reads the profile. Needs the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An account id from GET /api/v2/accounts."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"The brand the account is connected to, as for GET /api/v2/accounts."}],"responses":{"200":{"description":"Refresh result","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"handle":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string","enum":["updated","unchanged","unavailable"]},"refreshedAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"reconnectUrl":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the write scope, or a brand-bound key asking for another brand"},"404":{"description":"The account is not connected to this brand"},"429":{"description":"Rate or quota limit"},"502":{"description":"The refresh failed; retry"}}}},"/api/v2/accounts/{id}/reconnect":{"post":{"tags":["API v2"],"summary":"Start a reconnect (returns the OAuth link)","description":"Returns authUrl, the link a person opens (signed in to flayr, with this brand selected) to re-authorise the account. This call connects and disconnects nothing. Scheduled posts and the brand's default destination stay on the account: re-authorising the same page keeps its account id, and if the network issues a new id for the same page, the default and future bookings move to it when it syncs (audited). A shared-in account is reconnected in the brand that owns it. Needs the write scope and a plan with direct posting; every call is audited.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An account id from GET /api/v2/accounts."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"The brand the account is connected to, as for GET /api/v2/accounts."}],"responses":{"200":{"description":"The OAuth link","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"brandId":{"type":"string","nullable":true},"authUrl":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"The key's plan has no direct posting (UPGRADE_REQUIRED)"},"403":{"description":"The key lacks the write scope, or a brand-bound key asking for another brand"},"404":{"description":"The account is not connected to this brand"},"409":{"description":"The account is shared from another brand (reconnect it there), or the platform cannot be connected yet"},"429":{"description":"Rate or quota limit"},"502":{"description":"The link could not be created; retry"},"503":{"description":"Connecting accounts is not available right now"}}}},"/api/v2/accounts/defaults":{"put":{"tags":["API v2"],"summary":"Set the default destination for a platform","description":"Sets (or, with accountId null, clears) the brand's default account for one platform: where a post on that platform goes when no account is named. The same rule as the brand's Connections page: brand owners and admins only, and the account must be connected for that platform in the brand's organization. Personal has no defaults. Every change is audited. Needs the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"The brand, an id from GET /api/v2/brands (may also be sent in the body). Required unless the key is bound to a brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","accountId"],"properties":{"platform":{"type":"string","description":"e.g. instagram, tiktok, linkedin."},"accountId":{"type":"string","nullable":true,"description":"An account id from GET /api/v2/accounts for that platform, or null to clear the default."},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"The default now in force","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"platform":{"type":"string"},"accountId":{"type":"string","nullable":true},"message":{"type":"string"}}}}}},"400":{"description":"Bad body, or no brand named (Personal has no defaults)"},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the write scope, the caller is not a brand owner or admin, or a brand-bound key asking for another brand"},"422":{"description":"The account is not connected for that platform in the brand's organization"},"429":{"description":"Rate or quota limit"},"502":{"description":"The change failed; retry"}}}},"/api/v2/accounts/{id}/entry-points":{"get":{"tags":["API v2"],"summary":"Read a Page's DM entry points","description":"What a connected Instagram account or Facebook Page shows when someone opens a DM with it: the ice breaker questions, and on Facebook (Messenger) also the greeting, the Get Started button and the menu links. Also returns the question presets, link kinds and limits (`config`).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An Instagram or Facebook account id from GET /api/v2/accounts."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."}],"responses":{"200":{"description":"The entry points now live, plus config","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","enum":["instagram","facebook"]},"handle":{"type":"string","nullable":true},"iceBreakers":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"payload":{"type":"string"}}}},"greeting":{"type":"string","nullable":true},"menuLinks":{"type":"array","items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string","description":"Button title (up to 30 characters, or the configured limit)."},"url":{"type":"string","description":"An https:// link: the site, a booking page, a shop."}}}},"getStarted":{"type":"boolean"},"foreignPayloads":{"type":"array","items":{"type":"string"},"description":"Ice breakers or Get Started set outside flayr. A PUT of that field replaces them."}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the scope, a brand viewer, or a brand-bound key asking for another brand"},"404":{"description":"Not an Instagram or Facebook account of this brand (accounts shared in from another brand included)"},"429":{"description":"Rate or quota limit"},"502":{"description":"The social network did not answer; retry"}}},"put":{"tags":["API v2"],"summary":"Set a Page's DM entry points","description":"Changes what EVERY visitor sees when they open a DM with the account. A partial update: a field left out stays as is, null or [] removes it. Instagram takes iceBreakers only; a Facebook Page also takes greeting, menuLinks and getStarted (a menu turns Get Started on). Pass question text only: flayr sets the payloads. To answer a question automatically, add a DM trigger whose keyword is the question. Needs the publish scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An Instagram or Facebook account id from GET /api/v2/accounts."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"iceBreakers":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Up to 4 questions (up to 80 characters each), in order."},"greeting":{"type":"string","nullable":true,"description":"Facebook only. The welcome text shown before the first message (up to 160 characters)."},"menuLinks":{"type":"array","nullable":true,"items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string","description":"Button title (up to 30 characters, or the configured limit)."},"url":{"type":"string","description":"An https:// link: the site, a booking page, a shop."}}},"description":"Facebook only. The persistent menu, web links only."},"getStarted":{"type":"boolean","description":"Facebook only. Show the Get Started button."}}}}}},"responses":{"200":{"description":"The entry points now live","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string","enum":["instagram","facebook"]},"handle":{"type":"string","nullable":true},"iceBreakers":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"payload":{"type":"string"}}}},"greeting":{"type":"string","nullable":true},"menuLinks":{"type":"array","items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string","description":"Button title (up to 30 characters, or the configured limit)."},"url":{"type":"string","description":"An https:// link: the site, a booking page, a shop."}}}},"getStarted":{"type":"boolean"},"foreignPayloads":{"type":"array","items":{"type":"string"},"description":"Ice breakers or Get Started set outside flayr. A PUT of that field replaces them."}}}}}},"400":{"description":"Bad JSON or account id"},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the scope, a brand viewer, or a brand-bound key asking for another brand"},"404":{"description":"Not an Instagram or Facebook account of this brand (accounts shared in from another brand included)"},"422":{"description":"Invalid update (the errors list says why)"},"429":{"description":"Rate or quota limit"},"502":{"description":"The social network did not answer; retry"}}},"delete":{"tags":["API v2"],"summary":"Remove a Page's DM entry points","description":"Removes the ice breakers, and on Facebook also the greeting, menu and Get Started button, from the account. Every visitor stops seeing them. Needs the publish scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An Instagram or Facebook account id from GET /api/v2/accounts."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"platform":{"type":"string"},"cleared":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the scope, a brand viewer, or a brand-bound key asking for another brand"},"404":{"description":"Not an Instagram or Facebook account of this brand (accounts shared in from another brand included)"},"429":{"description":"Rate or quota limit"},"502":{"description":"The social network did not answer; retry"}}}},"/api/v2/attribution-rules":{"get":{"tags":["API v2"],"summary":"List attribution rules","description":"The brand's \"posts like this must carry a credit\" rules.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"responses":{"200":{"description":"The rules","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"mode":{"type":"string","enum":["flag","push_down"],"default":"flag","description":"What the brand's posting queues do with a draft that fails a rule. `flag` (default): show it (queue items' `attribution`, Needs review) and book as before. `push_down`: skip it when its turn comes — the next compliant item takes the slot — and report `pushedDown` on the item until it has its credit. The post is never edited or deleted."},"rules":{"type":"array","items":{"type":"object","description":"A rule is met by a structured credit on the draft (`credits`, see PATCH /api/v2/content/{id}) of the required kind, or by a credit written into the caption that flayr recognises (\"Print your own: <link> (model by X)\", a MakerWorld / Printables / Thingiverse link, \"Credit: …\", \"Music: …\"). flayr only checks that a credit exists with the fields asked for — it does not judge licenses.","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"name":{"type":"string","maxLength":80,"example":"Prints need a model credit"},"enabled":{"type":"boolean","default":true},"media":{"type":"string","enum":["any","video","image"],"default":"any","description":"Which posts the rule covers by media."},"label":{"type":"string","nullable":true,"example":"lane:prints","description":"Only posts carrying this `key:value` label. null = no label condition."},"creditKind":{"type":"string","enum":["model","music","footage","image","other"],"nullable":true,"description":"The credit kind required; null = any credit."},"requireAuthor":{"type":"boolean","default":false,"description":"The credit must name its author (designer / artist)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"A brand-bound key asked for another brand"},"404":{"description":"Unknown brand"}}},"post":{"tags":["API v2"],"summary":"Create an attribution rule","description":"Agency+ and the `publish` scope (same bar as posting queues).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80,"example":"Prints need a model credit"},"enabled":{"type":"boolean","default":true},"media":{"type":"string","enum":["any","video","image"],"default":"any","description":"Which posts the rule covers by media."},"label":{"type":"string","nullable":true,"example":"lane:prints","description":"Only posts carrying this `key:value` label. null = no label condition."},"creditKind":{"type":"string","enum":["model","music","footage","image","other"],"nullable":true,"description":"The credit kind required; null = any credit."},"requireAuthor":{"type":"boolean","default":false,"description":"The credit must name its author (designer / artist)."},"brandId":{"type":"string"}}}}}},"responses":{"201":{"description":"The rule","content":{"application/json":{"schema":{"type":"object","description":"A rule is met by a structured credit on the draft (`credits`, see PATCH /api/v2/content/{id}) of the required kind, or by a credit written into the caption that flayr recognises (\"Print your own: <link> (model by X)\", a MakerWorld / Printables / Thingiverse link, \"Credit: …\", \"Music: …\"). flayr only checks that a credit exists with the fields asked for — it does not judge licenses.","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"name":{"type":"string","maxLength":80,"example":"Prints need a model credit"},"enabled":{"type":"boolean","default":true},"media":{"type":"string","enum":["any","video","image"],"default":"any","description":"Which posts the rule covers by media."},"label":{"type":"string","nullable":true,"example":"lane:prints","description":"Only posts carrying this `key:value` label. null = no label condition."},"creditKind":{"type":"string","enum":["model","music","footage","image","other"],"nullable":true,"description":"The credit kind required; null = any credit."},"requireAuthor":{"type":"boolean","default":false,"description":"The credit must name its author (designer / artist)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Plan / scope / brand not allowed"},"422":{"description":"Invalid rule"}}}},"/api/v2/attribution-rules/settings":{"get":{"tags":["API v2"],"summary":"Get the brand's attribution enforcement mode","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"responses":{"200":{"description":"The mode","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"mode":{"type":"string","enum":["flag","push_down"],"default":"flag","description":"What the brand's posting queues do with a draft that fails a rule. `flag` (default): show it (queue items' `attribution`, Needs review) and book as before. `push_down`: skip it when its turn comes — the next compliant item takes the slot — and report `pushedDown` on the item until it has its credit. The post is never edited or deleted."}}}}}},"404":{"description":"Unknown brand"}}},"patch":{"tags":["API v2"],"summary":"Set the brand's attribution enforcement mode","description":"Agency+ and the `publish` scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["flag","push_down"],"default":"flag","description":"What the brand's posting queues do with a draft that fails a rule. `flag` (default): show it (queue items' `attribution`, Needs review) and book as before. `push_down`: skip it when its turn comes — the next compliant item takes the slot — and report `pushedDown` on the item until it has its credit. The post is never edited or deleted."},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"The mode","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"mode":{"type":"string","enum":["flag","push_down"],"default":"flag","description":"What the brand's posting queues do with a draft that fails a rule. `flag` (default): show it (queue items' `attribution`, Needs review) and book as before. `push_down`: skip it when its turn comes — the next compliant item takes the slot — and report `pushedDown` on the item until it has its credit. The post is never edited or deleted."}}}}}},"422":{"description":"Invalid mode"}}}},"/api/v2/attribution-rules/{id}":{"get":{"tags":["API v2"],"summary":"Get an attribution rule","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"responses":{"200":{"description":"The rule","content":{"application/json":{"schema":{"type":"object","description":"A rule is met by a structured credit on the draft (`credits`, see PATCH /api/v2/content/{id}) of the required kind, or by a credit written into the caption that flayr recognises (\"Print your own: <link> (model by X)\", a MakerWorld / Printables / Thingiverse link, \"Credit: …\", \"Music: …\"). flayr only checks that a credit exists with the fields asked for — it does not judge licenses.","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"name":{"type":"string","maxLength":80,"example":"Prints need a model credit"},"enabled":{"type":"boolean","default":true},"media":{"type":"string","enum":["any","video","image"],"default":"any","description":"Which posts the rule covers by media."},"label":{"type":"string","nullable":true,"example":"lane:prints","description":"Only posts carrying this `key:value` label. null = no label condition."},"creditKind":{"type":"string","enum":["model","music","footage","image","other"],"nullable":true,"description":"The credit kind required; null = any credit."},"requireAuthor":{"type":"boolean","default":false,"description":"The credit must name its author (designer / artist)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Not found in this workspace"}}},"patch":{"tags":["API v2"],"summary":"Edit an attribution rule","description":"Only the fields sent change; `label: null` / `creditKind: null` clear them. Agency+ and the `publish` scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80,"example":"Prints need a model credit"},"enabled":{"type":"boolean","default":true},"media":{"type":"string","enum":["any","video","image"],"default":"any","description":"Which posts the rule covers by media."},"label":{"type":"string","nullable":true,"example":"lane:prints","description":"Only posts carrying this `key:value` label. null = no label condition."},"creditKind":{"type":"string","enum":["model","music","footage","image","other"],"nullable":true,"description":"The credit kind required; null = any credit."},"requireAuthor":{"type":"boolean","default":false,"description":"The credit must name its author (designer / artist)."},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"The rule","content":{"application/json":{"schema":{"type":"object","description":"A rule is met by a structured credit on the draft (`credits`, see PATCH /api/v2/content/{id}) of the required kind, or by a credit written into the caption that flayr recognises (\"Print your own: <link> (model by X)\", a MakerWorld / Printables / Thingiverse link, \"Credit: …\", \"Music: …\"). flayr only checks that a credit exists with the fields asked for — it does not judge licenses.","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"\"personal\" or a brand id."},"name":{"type":"string","maxLength":80,"example":"Prints need a model credit"},"enabled":{"type":"boolean","default":true},"media":{"type":"string","enum":["any","video","image"],"default":"any","description":"Which posts the rule covers by media."},"label":{"type":"string","nullable":true,"example":"lane:prints","description":"Only posts carrying this `key:value` label. null = no label condition."},"creditKind":{"type":"string","enum":["model","music","footage","image","other"],"nullable":true,"description":"The credit kind required; null = any credit."},"requireAuthor":{"type":"boolean","default":false,"description":"The credit must name its author (designer / artist)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Not found in this workspace"},"422":{"description":"Invalid field"}}},"delete":{"tags":["API v2"],"summary":"Delete an attribution rule","description":"Drafts and posts are never touched. Agency+ and the `publish` scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"string"}}}}}},"404":{"description":"Not found in this workspace"}}}},"/api/v2/analytics/signup-sources":{"get":{"tags":["API v2"],"summary":"Sign-ups by source (owner brand only)","description":"FFE-1476: accounts created in the last N UTC days, with their first published post and first paid activation, per sign-up source: paid:<network>, organic, outreach, friends_family, internal or unknown. `totals.acquired` is net of friends/family, outreach and internal. FFE-1572: `campaigns` splits the same accounts by utm_campaign, utm_content, utm_term (ad set) and landing path of the touch that names the campaign, plus campaign × landing and campaign × content; `paidSource` counts sign-ups whose source is paid. Counts only, never an identity. Platform-wide data: only a key bound to the owner brand (held by someone with a role on it) or a super-admin's key gets 200; every other caller gets 403. Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,14,30,90],"default":30}},{"name":"campaign","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:~-]{1,100}$"},"description":"Keep only campaigns whose utm_campaign starts with this (e.g. fl-w1-). Filters `campaigns` only."}],"responses":{"200":{"description":"Source breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"from":{"type":"integer"},"to":{"type":"integer"},"cutoff":{"type":"integer"},"rows":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"kind":{"type":"string"},"network":{"type":"string","nullable":true},"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"}}}},"totals":{"type":"object","properties":{"all":{"type":"object","properties":{"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"}}},"paid":{"type":"object","properties":{"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"}}},"acquired":{"type":"object","properties":{"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"}}},"notAcquired":{"type":"object","properties":{"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"}}}}},"campaigns":{"type":"object","properties":{"campaignPrefix":{"type":"string","nullable":true},"totals":{"type":"object","properties":{"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"},"paidSource":{"type":"integer"}}},"byCampaign":{"type":"array","items":{"type":"object","properties":{"campaign":{"type":"string"},"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"},"paidSource":{"type":"integer"}}}},"byContent":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"},"paidSource":{"type":"integer"}}}},"byTerm":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"},"paidSource":{"type":"integer"}}}},"byLanding":{"type":"array","items":{"type":"object","properties":{"landing":{"type":"string"},"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"},"paidSource":{"type":"integer"}}}},"campaignByLanding":{"type":"array","items":{"type":"object","properties":{"campaign":{"type":"string"},"landing":{"type":"string"},"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"},"paidSource":{"type":"integer"}}}},"campaignByContent":{"type":"array","items":{"type":"object","properties":{"campaign":{"type":"string"},"content":{"type":"string"},"signups":{"type":"integer"},"firstPosts":{"type":"integer"},"paid":{"type":"integer"},"paidSource":{"type":"integer"}}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Analytics not on this plan (Pro+)"},"403":{"description":"Not the owner brand, or no role on it"},"422":{"description":"Invalid days or campaign"}}}},"/api/v2/analytics/traffic":{"get":{"tags":["API v2"],"summary":"Post → site traffic (UTM visits per post and label)","description":"Site visits sent by flayr-managed links. Publishing adds utm_source=<platform>, utm_medium=social, utm_campaign=<campaign label or brand slug> and utm_content=<draft id> to the CTA destination and first-comment links (never to a link typed in the caption, never over an existing utm_*; a brand can turn it off). PostHog $pageviews are read once a day and joined back to the post. A post with no tracked visit is not reported, not 0. Needs the analytics plan feature.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id, or \"all\" (default). A brand-bound key is always its own brand."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90],"default":30}},{"name":"breakdown","in":"query","required":false,"schema":{"type":"string","default":"platform"},"description":"platform, brand, campaign, weekday, hour, postType or label:<key>."},{"name":"tzOffsetMinutes","in":"query","required":false,"schema":{"type":"integer","minimum":-840,"maximum":840}}],"responses":{"200":{"description":"Traffic summary","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","enum":[7,30,90]},"dateFrom":{"type":"number","description":"Epoch ms: posts published from here…"},"dateTo":{"type":"number","description":"…to here."},"siteVisits":{"type":"object","properties":{"value":{"type":"number","nullable":true,"description":"Total site visits. null = no post in range has a tracked visit (never a fake 0)."},"posts":{"type":"integer","description":"Posts published in range."},"withVisits":{"type":"integer","description":"Posts with at least one tracked visit."},"notReported":{"type":"integer","description":"Posts with no tracked visit (no flayr-managed link, UTM off, or no visit)."},"pending":{"type":"integer","description":"Posts too recent for the daily read."}}},"visitsPer1kReach":{"type":"number","nullable":true,"description":"Pooled: Σ visits × 1000 ÷ Σ reach (reach = larger of impressions and views)."},"breakdown":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"Raw value per breakdown (ids for brand / campaign / experiment; \"(none)\" when the post has no value)."},"labels":{"type":"array","items":{"type":"string"},"description":"Display name per breakdown."},"value":{"type":"number","nullable":true,"description":"The aggregate. null = no post in the group has data for this metric (never a fake 0)."},"n":{"type":"integer","description":"Units with data: the sample size."},"units":{"type":"integer","description":"Units in the group (posts, or post × platform with a platform breakdown)."},"notReported":{"type":"integer","description":"Units only on platforms that do not report this metric (left out)."},"pending":{"type":"integer","description":"Units whose snapshot for this window is not captured yet (left out)."},"lowSample":{"type":"boolean","description":"n below 3: not enough data yet."}}}},"topPosts":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"publishedAt":{"type":"number"},"platforms":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"visits":{"type":"integer"}}}},"notes":{"type":"array","items":{"type":"string"}},"truncated":{"type":"boolean"},"utm":{"type":"object","nullable":true,"description":"When the scope is one brand: its UTM switch (owners and admins change it in the app).","properties":{"clientProfileId":{"type":"string"},"enabled":{"type":"boolean"},"canEdit":{"type":"boolean"}}}}}}}},"402":{"description":"Analytics not on this plan (Pro+)"},"403":{"description":"Another brand for a brand-bound key"},"404":{"description":"Unknown brand"},"422":{"description":"Invalid days / breakdown / tzOffsetMinutes"}}}},"/api/v2/insights/query":{"post":{"tags":["API v2"],"summary":"Run a custom insight","description":"The same definition the Insights → Dashboards builder saves. Reads the pre-aggregated 48h / 7d / 30d / lifetime post snapshots, so posts are compared at the same age. Platforms that do not report a metric are left out and listed in `availability` (never counted as 0). Every row carries its n; nothing is statistically tested. referralClicks is account-wide (split only by platform, weekday or hour) and not available to a brand scope. Needs the analytics plan (Pro+). Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"],"default":"json"},"description":"csv = the result as a spreadsheet-safe CSV attachment (UTF-8 BOM, CRLF, cells starting with = + - @ are prefixed with '). Without `format`, `Accept: text/csv` also selects CSV. Errors are always JSON."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","ctr","reach","likes","comments","shares","saves","followersGained","watchTimeHours","avgWatchSeconds","completionRate","postsPublished","referralClicks","siteVisits","visitsPer1kReach"],"default":"impressions"},"aggregation":{"type":"string","enum":["sum","mean","median","p90","count","pooled"],"default":"median","description":"Default median; pooled for the rates engagementRate, ctr and completionRate. A rate is pooled (Σ numerator ÷ Σ denominator), mean, median or count, never sum or p90. Pooled applies to rates only."},"breakdown":{"type":"array","maxItems":2,"items":{"type":"string"},"description":"Up to 2 of: platform, brand, campaign, experiment, arm, weekday, hour, postType, or label:<key> (e.g. label:cut, label:line, label:source, label:hook, label:series). The multi-valued format key also splits per group: label:format@length, label:format@style, label:format@non_video, label:format@method (a post counts once in each, never twice in one). A post with no source: label (or no length) falls back to how it was made; those rows have `derived` > 0 and a \"derived\" label, and no label is written. \"arm\" = the experiment's compareKey and needs filters.experimentId."},"window":{"type":"string","enum":["48h","7d","30d","lifetime"],"default":"7d","description":"Snapshot age: the metric as it stood 48h / 7d / 30d after publish, or the latest refresh."},"interval":{"type":"string","enum":["day","week","month"],"description":"Adds a time series bucketed by publish date."},"filters":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"string"},"maxItems":5,"description":"Every label must be on the post (key:value)."},"excludeLabels":{"type":"array","items":{"type":"string"},"maxItems":5,"description":"Posts with any of these labels are left out (the tag templates exclude line:test)."},"campaignId":{"type":"string"},"experimentId":{"type":"string","description":"Reads the experiment over its own start–end window."},"platforms":{"type":"array","items":{"type":"string"}}}},"dateFrom":{"type":"string","description":"ISO date or epoch ms (publish time). Default: 90 days ago; ranges are capped at 400 days."},"dateTo":{"type":"string","description":"ISO date or epoch ms. Default: now."},"tzOffsetMinutes":{"type":"integer","description":"Offset from UTC for weekday / hour / day buckets (e.g. -300)."},"brandId":{"type":"string","description":"A brand id, or \"all\" (default: every profile you can see). A brand-bound key is always its own brand."},"formula":{"type":"object","description":"Optional (needs the Advanced insights feature): combine up to three series. Each series is a metric + aggregation over the same breakdown, window, interval, filters and range. `expression` (≤ 80 characters) uses A, B, C, numbers, + - * / and parentheses, e.g. \"A / B\". Rows are joined on their keys; a group missing from any series, or a division by zero, is null. n = the smallest n across series. `metric` defaults to (and must equal) series A's. Referral series can only be split by platform, weekday or hour.","required":["series","expression"],"properties":{"series":{"type":"object","required":["A"],"properties":{"A":{"type":"object","required":["metric"],"properties":{"metric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","ctr","reach","likes","comments","shares","saves","followersGained","watchTimeHours","avgWatchSeconds","completionRate","postsPublished","referralClicks","siteVisits","visitsPer1kReach"]},"aggregation":{"type":"string","enum":["sum","mean","median","p90","count","pooled"]}}},"B":{"type":"object","required":["metric"],"properties":{"metric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","ctr","reach","likes","comments","shares","saves","followersGained","watchTimeHours","avgWatchSeconds","completionRate","postsPublished","referralClicks","siteVisits","visitsPer1kReach"]},"aggregation":{"type":"string","enum":["sum","mean","median","p90","count","pooled"]}}},"C":{"type":"object","required":["metric"],"properties":{"metric":{"type":"string","enum":["impressions","views","engagement","engagementRate","clicks","ctr","reach","likes","comments","shares","saves","followersGained","watchTimeHours","avgWatchSeconds","completionRate","postsPublished","referralClicks","siteVisits","visitsPer1kReach"]},"aggregation":{"type":"string","enum":["sum","mean","median","p90","count","pooled"]}}}}},"expression":{"type":"string","maxLength":80},"format":{"type":"string","enum":["number","percent"],"default":"number","description":"percent = a ratio shown ×100 with a % sign."}},"example":{"series":{"A":{"metric":"clicks","aggregation":"sum"},"B":{"metric":"impressions","aggregation":"sum"}},"expression":"A / B","format":"percent"}}},"example":{"metric":"impressions","aggregation":"median","breakdown":["label:cut","platform"],"window":"7d"}}}}},"responses":{"200":{"description":"Insight result (JSON), or the same result as a CSV attachment with `format=csv` / `Accept: text/csv`","headers":{"Content-Disposition":{"description":"CSV only: attachment; filename=\"insight-YYYY-MM-DD.csv\"","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string"},"aggregation":{"type":"string"},"window":{"type":"string","enum":["h48","d7","d30","lifetime"]},"breakdown":{"type":"array","items":{"type":"string"}},"unit":{"type":"string","enum":["post","post_platform","click"]},"rows":{"type":"array","items":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"Raw value per breakdown (ids for brand / campaign / experiment; \"(none)\" when the post has no value)."},"labels":{"type":"array","items":{"type":"string"},"description":"Display name per breakdown."},"value":{"type":"number","nullable":true,"description":"The aggregate. null = no post in the group has data for this metric (never a fake 0)."},"n":{"type":"integer","description":"Units with data: the sample size."},"units":{"type":"integer","description":"Units in the group (posts, or post × platform with a platform breakdown)."},"notReported":{"type":"integer","description":"Units only on platforms that do not report this metric (left out)."},"pending":{"type":"integer","description":"Units whose snapshot for this window is not captured yet (left out)."},"lowSample":{"type":"boolean","description":"n below 3: not enough data yet."}}}},"total":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"Raw value per breakdown (ids for brand / campaign / experiment; \"(none)\" when the post has no value)."},"labels":{"type":"array","items":{"type":"string"},"description":"Display name per breakdown."},"value":{"type":"number","nullable":true,"description":"The aggregate. null = no post in the group has data for this metric (never a fake 0)."},"n":{"type":"integer","description":"Units with data: the sample size."},"units":{"type":"integer","description":"Units in the group (posts, or post × platform with a platform breakdown)."},"notReported":{"type":"integer","description":"Units only on platforms that do not report this metric (left out)."},"pending":{"type":"integer","description":"Units whose snapshot for this window is not captured yet (left out)."},"lowSample":{"type":"boolean","description":"n below 3: not enough data yet."}}},"series":{"type":"object","description":"With `interval`: buckets (epoch ms) and one line per group (the 8 largest). null values are buckets with no data.","properties":{"buckets":{"type":"array","items":{"type":"number"}},"lines":{"type":"array","items":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"values":{"type":"array","items":{"type":"number","nullable":true}},"n":{"type":"array","items":{"type":"integer"}}}}}}},"availability":{"type":"array","description":"Per platform in the result: whether it reports the metric, and how many units have data.","items":{"type":"object","properties":{"platform":{"type":"string"},"reported":{"type":"boolean"},"posts":{"type":"integer"},"withData":{"type":"integer"}}}},"sample":{"type":"object","properties":{"minN":{"type":"integer"},"enough":{"type":"boolean"}}},"notes":{"type":"array","items":{"type":"string"}},"truncated":{"type":"boolean","description":"More than 500 posts in scope: only the newest 500 were read."},"formula":{"type":"object","description":"Present for a formula insight: how to show the value.","properties":{"expression":{"type":"string"},"format":{"type":"string","enum":["number","percent"]}}}}}},"text/csv":{"schema":{"type":"string","description":"Columns: insight, <breakdown labels…>, value, formatted value, n, pending, not reported, low sample, notes (a time series adds date). Notes are in the last column of the first row."}}}},"400":{"description":"Body is not JSON"},"402":{"description":"Analytics not on this plan"},"403":{"description":"Another brand for a brand-bound key"},"404":{"description":"Unknown brand"},"422":{"description":"Invalid definition or format, or a formula without the Advanced insights feature"}}}},"/api/v2/insights/dashboards":{"get":{"tags":["API v2"],"summary":"List saved insight dashboards","description":"Every dashboard the key owner can see (their own, their organizations' and their brands'), newest first, at most 50. A brand-bound key sees only its brand's dashboards. Needs the analytics plan (Pro+). Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Only this brand's dashboards, or \"all\" (default)."}],"responses":{"200":{"description":"Dashboards","content":{"application/json":{"schema":{"type":"object","properties":{"dashboards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brandId":{"type":"string","nullable":true,"description":"The brand the dashboard belongs to; null for a personal or all-profiles dashboard."},"allProfiles":{"type":"boolean","description":"Tiles run across every profile the viewer can see."},"template":{"type":"string","nullable":true,"enum":["blank","ab_experiment","campaign_performance","by_line","by_format","by_format_length","by_format_style","by_series","by_source","by_hook","what_we_made",null]},"isBrandDefault":{"type":"boolean","description":"The brand's default dashboard (at most one per brand)."},"filters":{"type":"object","properties":{"range":{"type":"string","enum":["7d","30d","90d","180d","365d"]},"platforms":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}}}},"tiles":{"type":"array","maxItems":12,"items":{"type":"object","required":["title","view","query"],"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_]{1,40}$","description":"Generated when omitted on create."},"title":{"type":"string","maxLength":120},"view":{"type":"string","enum":["bar","line","table","number","arms"],"description":"\"arms\" needs an arm breakdown."},"width":{"type":"integer","enum":[1,2],"default":1,"description":"1 = half row, 2 = full row."},"query":{"type":"object","description":"The same definition as POST /api/v2/insights/query, without dateFrom, dateTo, tzOffsetMinutes or brandId (the dashboard supplies them)."}}}},"updatedAt":{"type":"number","description":"Epoch ms."},"canEdit":{"type":"boolean","description":"The key owner may change this dashboard (in the app)."}}}}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Analytics not on this plan"},"403":{"description":"Another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}},"post":{"tags":["API v2"],"summary":"Create a saved insight dashboard","description":"Creates a dashboard from a template, optionally replacing its tiles. A formula tile needs the Advanced insights feature (else 422). Requires the `write` scope and the analytics plan (Pro+).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"template":{"type":"string","enum":["blank","ab_experiment","campaign_performance","by_line","by_format","by_format_length","by_format_style","by_series","by_source","by_hook","what_we_made"],"default":"blank"},"experimentId":{"type":"string","description":"Required for the ab_experiment template."},"brandId":{"type":"string","description":"A brand id (GET /api/v2/brands), or \"all\" for every profile you can see. Omitted: your active brand. A brand-bound key always creates in its own brand."},"tiles":{"type":"array","maxItems":12,"items":{"type":"object","required":["title","view","query"],"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_]{1,40}$","description":"Generated when omitted on create."},"title":{"type":"string","maxLength":120},"view":{"type":"string","enum":["bar","line","table","number","arms"],"description":"\"arms\" needs an arm breakdown."},"width":{"type":"integer","enum":[1,2],"default":1,"description":"1 = half row, 2 = full row."},"query":{"type":"object","description":"The same definition as POST /api/v2/insights/query, without dateFrom, dateTo, tzOffsetMinutes or brandId (the dashboard supplies them)."}}},"description":"Replaces the template's tiles."}},"example":{"name":"Agent board","template":"campaign_performance"}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"400":{"description":"Body is not JSON"},"401":{"description":"Missing or invalid API key"},"402":{"description":"Analytics not on this plan"},"403":{"description":"Key lacks the write scope"},"404":{"description":"Unknown brand"},"422":{"description":"Invalid name, template, experiment or tile, or a formula tile without the Advanced insights feature"}}}},"/api/v2/insights/dashboards/{id}":{"get":{"tags":["API v2"],"summary":"Get a saved insight dashboard","description":"Needs the analytics plan (Pro+). Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dashboard","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brandId":{"type":"string","nullable":true,"description":"The brand the dashboard belongs to; null for a personal or all-profiles dashboard."},"allProfiles":{"type":"boolean","description":"Tiles run across every profile the viewer can see."},"template":{"type":"string","nullable":true,"enum":["blank","ab_experiment","campaign_performance","by_line","by_format","by_format_length","by_format_style","by_series","by_source","by_hook","what_we_made",null]},"isBrandDefault":{"type":"boolean","description":"The brand's default dashboard (at most one per brand)."},"filters":{"type":"object","properties":{"range":{"type":"string","enum":["7d","30d","90d","180d","365d"]},"platforms":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}}}},"tiles":{"type":"array","maxItems":12,"items":{"type":"object","required":["title","view","query"],"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_]{1,40}$","description":"Generated when omitted on create."},"title":{"type":"string","maxLength":120},"view":{"type":"string","enum":["bar","line","table","number","arms"],"description":"\"arms\" needs an arm breakdown."},"width":{"type":"integer","enum":[1,2],"default":1,"description":"1 = half row, 2 = full row."},"query":{"type":"object","description":"The same definition as POST /api/v2/insights/query, without dateFrom, dateTo, tzOffsetMinutes or brandId (the dashboard supplies them)."}}}},"updatedAt":{"type":"number","description":"Epoch ms."},"canEdit":{"type":"boolean","description":"The key owner may change this dashboard (in the app)."}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Analytics not on this plan"},"404":{"description":"No such dashboard, not readable by the key owner, or outside a brand-bound key's brand"}}}},"/api/v2/insights/dashboards/{id}/run":{"post":{"tags":["API v2"],"summary":"Run every tile on a saved dashboard","description":"Runs the tiles in order over the dashboard's shared date range and filters, in its scope (all profiles, or its brand). A tile the key owner cannot run comes back as `error` (e.g. a formula without the Advanced insights feature); the other tiles still run. Needs the analytics plan (Pro+). Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"string","enum":["7d","30d","90d","180d","365d"],"description":"Overrides the dashboard's saved range for this run."},"tzOffsetMinutes":{"type":"integer","minimum":-840,"maximum":840,"default":0,"description":"Offset from UTC for weekday / hour / day buckets."}},"example":{"range":"90d"}}}}},"responses":{"200":{"description":"One result per tile, in tile order","content":{"application/json":{"schema":{"type":"object","properties":{"dashboard":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"range":{"type":"string","enum":["7d","30d","90d","180d","365d"]}}},"results":{"type":"array","items":{"type":"object","properties":{"tileId":{"type":"string"},"title":{"type":"string"},"view":{"type":"string","enum":["bar","line","table","number","arms"]},"result":{"type":"object","properties":{"metric":{"type":"string"},"aggregation":{"type":"string"},"window":{"type":"string","enum":["h48","d7","d30","lifetime"]},"breakdown":{"type":"array","items":{"type":"string"}},"unit":{"type":"string","enum":["post","post_platform","click"]},"rows":{"type":"array","items":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"Raw value per breakdown (ids for brand / campaign / experiment; \"(none)\" when the post has no value)."},"labels":{"type":"array","items":{"type":"string"},"description":"Display name per breakdown."},"value":{"type":"number","nullable":true,"description":"The aggregate. null = no post in the group has data for this metric (never a fake 0)."},"n":{"type":"integer","description":"Units with data: the sample size."},"units":{"type":"integer","description":"Units in the group (posts, or post × platform with a platform breakdown)."},"notReported":{"type":"integer","description":"Units only on platforms that do not report this metric (left out)."},"pending":{"type":"integer","description":"Units whose snapshot for this window is not captured yet (left out)."},"lowSample":{"type":"boolean","description":"n below 3: not enough data yet."}}}},"total":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"Raw value per breakdown (ids for brand / campaign / experiment; \"(none)\" when the post has no value)."},"labels":{"type":"array","items":{"type":"string"},"description":"Display name per breakdown."},"value":{"type":"number","nullable":true,"description":"The aggregate. null = no post in the group has data for this metric (never a fake 0)."},"n":{"type":"integer","description":"Units with data: the sample size."},"units":{"type":"integer","description":"Units in the group (posts, or post × platform with a platform breakdown)."},"notReported":{"type":"integer","description":"Units only on platforms that do not report this metric (left out)."},"pending":{"type":"integer","description":"Units whose snapshot for this window is not captured yet (left out)."},"lowSample":{"type":"boolean","description":"n below 3: not enough data yet."}}},"series":{"type":"object","description":"With `interval`: buckets (epoch ms) and one line per group (the 8 largest). null values are buckets with no data.","properties":{"buckets":{"type":"array","items":{"type":"number"}},"lines":{"type":"array","items":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"values":{"type":"array","items":{"type":"number","nullable":true}},"n":{"type":"array","items":{"type":"integer"}}}}}}},"availability":{"type":"array","description":"Per platform in the result: whether it reports the metric, and how many units have data.","items":{"type":"object","properties":{"platform":{"type":"string"},"reported":{"type":"boolean"},"posts":{"type":"integer"},"withData":{"type":"integer"}}}},"sample":{"type":"object","properties":{"minN":{"type":"integer"},"enough":{"type":"boolean"}}},"notes":{"type":"array","items":{"type":"string"}},"truncated":{"type":"boolean","description":"More than 500 posts in scope: only the newest 500 were read."},"formula":{"type":"object","description":"Present for a formula insight: how to show the value.","properties":{"expression":{"type":"string"},"format":{"type":"string","enum":["number","percent"]}}}}},"error":{"type":"string","description":"Set instead of result when this tile could not run."}}}}}}}}},"400":{"description":"Body is not JSON"},"401":{"description":"Missing or invalid API key"},"402":{"description":"Analytics not on this plan"},"404":{"description":"No such dashboard, not readable by the key owner, or outside a brand-bound key's brand"},"422":{"description":"Invalid range or tzOffsetMinutes"}}}},"/api/v2/analytics/health":{"get":{"tags":["API v2"],"summary":"Metrics sync health","description":"When each connected account's post metrics last synced, so a data gap is not read as a real drop. Scope: the key's brand (a brand-bound key) or the owner's active brand. An account is `stale` when its data is 24 h behind its refresh schedule and `gap` at 72 h, or when it is disconnected or analytics is not provisioned; `pending` means not synced yet. `summary.completeThrough` is the oldest last successful sync (ms epoch), null until any account synced. Missing values are null, never 0. Pro+ required.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Summary and per-account health","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"summary":{"type":"object","properties":{"status":{"type":"string","enum":["green","stale","gap","pending"]},"completeThrough":{"type":"number","nullable":true},"accounts":{"type":"integer"},"stale":{"type":"integer"},"gap":{"type":"integer"},"pending":{"type":"integer"},"checkedAt":{"type":"number"}}},"accounts":{"type":"array","items":{"type":"object","properties":{"zernioAccountId":{"type":"string"},"platform":{"type":"string"},"handle":{"type":"string","nullable":true},"status":{"type":"string","enum":["green","stale","gap","pending"]},"reason":{"type":"string"},"lastSuccessAt":{"type":"number","nullable":true},"lastAttemptAt":{"type":"number","nullable":true},"lastErrorKind":{"type":"string","nullable":true,"enum":["rate_limited","addon_missing","disconnected","zernio_error","no_posts",null]},"postsTracked":{"type":"number","nullable":true},"postsFresh":{"type":"number","nullable":true},"shared":{"type":"boolean","description":"Shared into the brand by another brand."}}}}}}}}},"402":{"description":"Pro+ required"},"404":{"description":"The key has no analytics scope (its brand is inactive or the owner left it)."}}}},"/api/v2/analytics/instances":{"get":{"tags":["API v2"],"summary":"Compare post instances and reruns","description":"Per-account metrics and sum roll-ups by post, instance, tag, campaign, experiment and series. Historical platform-only rows remain platform-attributed. Pending/failed sync rows are excluded from totals. Pro plan or higher.","security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"query","required":false,"schema":{"type":"string"},"description":"Local Flayr post id; omit for roll-ups across the readable scope (up to 100 posts)."},{"name":"includeReruns","in":"query","schema":{"type":"boolean","default":false},"description":"Compare all readable bookings of the same contentId."},{"name":"brandId","in":"query","schema":{"type":"string"},"description":"Brand id or all; brand-bound keys remain pinned."}],"responses":{"200":{"description":"Instances (postId, instanceKey, accountId, repostIndex, labels, timestamps, syncStatus, impressions, engagement, clicks), rollups (dimension, key, totals, instances, posts), and truncated."},"404":{"description":"Post unavailable in this scope."},"422":{"description":"Invalid parameters."}}}},"/api/v2/insights/whats-working":{"get":{"tags":["API v2"],"summary":"What's working / what isn't","description":"The brand's top and bottom 3 label, format and platform values by engagement-rate lift over the last 30 days. Engagement rate is pooled: Σ engagement ÷ Σ reach, reach = max(impressions, views). A value needs 5 posts; `line:test` posts, pending metrics and platforms that do not report reach (X, Bluesky) are left out. Scope: the key's brand (a brand-bound key) or the owner's resolved analytics scope (Personal when no brand resolves). `brandEr` is null without reach, never 0. Pro+ required.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Winners and losers by ER lift","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"brandEr":{"type":"number","nullable":true},"posts":{"type":"integer","description":"Eligible posts in the window."},"minN":{"type":"integer"},"lookbackDays":{"type":"integer"},"truncated":{"type":"boolean","description":"More posts than one read covers; the ranking uses the newest."},"winners":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string","enum":["label:line","label:format@length","label:format@style","label:source","label:hook","label:series","platform"]},"value":{"type":"string","description":"The label value (`personal` for `line:personal`) or the platform slug."},"n":{"type":"integer","description":"Distinct posts behind the value."},"er":{"type":"number","description":"Pooled reach engagement rate of the value, in %."},"brandEr":{"type":"number","description":"Pooled reach engagement rate of the brand, in %."},"liftPts":{"type":"number","description":"er − brandEr, in percentage points."},"reachPerSlot":{"type":"number","description":"Σ reach ÷ n."}}}},"losers":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string","enum":["label:line","label:format@length","label:format@style","label:source","label:hook","label:series","platform"]},"value":{"type":"string","description":"The label value (`personal` for `line:personal`) or the platform slug."},"n":{"type":"integer","description":"Distinct posts behind the value."},"er":{"type":"number","description":"Pooled reach engagement rate of the value, in %."},"brandEr":{"type":"number","description":"Pooled reach engagement rate of the brand, in %."},"liftPts":{"type":"number","description":"er − brandEr, in percentage points."},"reachPerSlot":{"type":"number","description":"Σ reach ÷ n."}}}}}}}}},"402":{"description":"Pro+ required"},"404":{"description":"The key has no analytics scope, or What's working is not enabled for the account."}}}},"/api/v2/content/{id}/booth-take":{"post":{"tags":["API v2"],"summary":"Attach a recorded voice-over take to a video (async)","description":"Mixes ONE continuous recording of a person's voice onto the video `{id}`, saved as a NEW linked draft labelled `variant:booth` and `voice:human`. The original is never modified and nothing is posted. Upload the audio first (POST /api/v2/media/upload-url). A human recording adds no AI label; a character or generated video keeps the one it has. Refused with 422 when the video has a lip-synced character on camera. Free for now. Requires the write (or admin) scope. Pro+ plan. Returns 202 with a jobId: poll GET /api/v2/generate/status/{jobId}; when it is completed, `resultContentId` is the new draft.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The video to voice over."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["storageId","durationSeconds"],"additionalProperties":false,"properties":{"storageId":{"type":"string","description":"The uploaded take."},"durationSeconds":{"type":"number","description":"The video's length in seconds. The output is never longer."},"startAtSeconds":{"type":"number","minimum":0,"default":0,"description":"Where in the video the take starts."},"script":{"type":"string","description":"What was read, kept with the render for reference."}}}}}},"responses":{"202":{"description":"Queued: { jobId, status, embers }."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Plan does not include this."},"403":{"description":"Missing the write scope."},"404":{"description":"Video not found."},"422":{"description":"Invalid body, or a video the booth can't record over."},"429":{"description":"Rate limited."}}}},"/api/v2/content/{id}/combine":{"post":{"tags":["API v2"],"summary":"Combine clips into a finished video (async)","description":"Extends the video `{id}` with more clips and image cards into ONE finished video, rendered on flayr's render worker and saved as a NEW linked draft — same brand, caption copied, creator credits merged from every Library item used, labelled `variant:combined`. The original is never modified and nothing is posted. Example: show a finished 3D print with its painting / assembly clips before or after it, a title card up front and the thumbnail at the end. SEGMENTS (2-8, in order) must include this video itself as a clip. A clip is a Library video (`contentId`) or an upload (`storageId` from POST /api/v2/media/upload-url), cut to `inMs`-`outMs`; give `outMs`, or `durationMs` (the clip's full length) to use it to the end — the length must be known so the price is. A card is an image shown for `durationMs` (1000-10000; default 1500 as the opener, else 2500) with optional `text`: a Library image or a video's thumbnail (`contentId`) or an uploaded image (`imageStorageId`). Every Library item must be in the same brand as `{id}`. The piece keeps this video's frame (e.g. 9:16); clips or images of another aspect are shown whole over a blurred fill. Each segment is at least 1 s; the finished piece at most the account limit (60 min by default, never over 3 h) — long-form works: a cold open clip, this recording trimmed with `inMs`/`outMs`, bumpers. Output is H.264 + AAC with faststart. Audio: `keep` (each clip's own sound), `mute_extras` (only this video's sound), or `main_across` (this video's soundtrack under the whole piece); loudness-normalised to -14 LUFS. Credits: 25 Embers per started minute of the finished video for the first 3 minutes (the hive render price), then 5 per further started minute by default (a 15 min piece is 135), charged when queued and refunded if the render fails. Requires the write (or admin) scope. Pro+ plan. Returns 202 with a jobId: poll GET /api/v2/generate/status/{jobId}; when it is completed, `resultContentId` is the new draft.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The video to extend."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["segments"],"additionalProperties":false,"properties":{"segments":{"type":"array","minItems":2,"maxItems":8,"description":"In playback order. Must include this video ({ \"kind\": \"clip\", \"contentId\": \"<id>\" }).","items":{"type":"object","required":["kind"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["clip","card"]},"contentId":{"type":"string","description":"clip: a Library video. card: a Library image, or a video (its thumbnail)."},"storageId":{"type":"string","description":"clip only: an uploaded video (POST /api/v2/media/upload-url)."},"imageStorageId":{"type":"string","description":"card only: an uploaded image."},"inMs":{"type":"integer","minimum":0,"description":"clip only: where the clip starts (default 0)."},"outMs":{"type":"integer","minimum":0,"description":"clip only: where the clip ends. Defaults to durationMs."},"durationMs":{"type":"integer","minimum":1,"description":"clip: the source clip's full length (needed when outMs is omitted). card: how long it shows (1000-10000)."},"text":{"type":"string","maxLength":80,"description":"card only: one short line over the image."}}}},"transition":{"type":"string","enum":["cut","crossfade"],"default":"cut"},"crossfadeMs":{"type":"integer","minimum":300,"maximum":500,"default":400,"description":"Crossfade overlap per join."},"audio":{"type":"string","enum":["keep","mute_extras","main_across"],"default":"keep"}}}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["queued"]},"embers":{"type":"integer","description":"Embers charged (refunded if the render fails)."},"durationMs":{"type":"integer","description":"Length of the finished video."}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Pro+ plan required, or not enough Embers"},"403":{"description":"Missing write scope"},"404":{"description":"Video (or a segment's Library item) not found, not visible to this key, or in another brand"},"422":{"description":"Validation error (segments, lengths, limits), or an upload that is missing or not yours"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/generate/status/{jobId}":{"get":{"tags":["API v2"],"summary":"Job status","description":"Status of an async job from POST /api/v2/generate/video or POST /api/v2/content/{id}/combine. `source` says which: \"generation\" (AI video — `result` holds the output), \"video-compose\" (stock overlay — `renderedUrl`), or \"combine\" (`resultContentId` is the new draft once completed; a failed combine is refunded). status: pending · processing · completed · failed (AI jobs may also report their own states). A brand-bound key sees only its brand's jobs.","security":[{"bearerAuth":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"source":{"type":"string","enum":["generation","video-compose","combine"]},"status":{"type":"string"},"renderedUrl":{"type":"string","nullable":true},"errorMessage":{"type":"string","nullable":true},"resultContentId":{"type":"string","nullable":true,"description":"combine: the new draft."},"type":{"type":"string","description":"generation only."},"error":{"type":"string","nullable":true,"description":"generation only."},"result":{"type":"object","nullable":true,"description":"generation only."}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found, or not visible to this key"}}}},"/api/v2/media/large-upload":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Begin a resumable large-media upload","description":"For files above the configured size (default 60 MB), up to a long-form master. Accepts MP4, MOV, MKV and WebM, including Opus audio. A smaller file answers `{ path: \"convex\" }`: use POST /api/v2/media/upload-url. Otherwise send each part with `uploadPart` from the Vercel Blob client SDK (`access: \"private\"`, the returned `clientToken`, `multipartKey`, `multipartUploadId`), record each with action `part`, then action `complete`. Free. A full storage pool answers 413 before a byte moves.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string"},"contentType":{"type":"string"},"sizeBytes":{"type":"integer"}},"required":["fileName","sizeBytes"]}}}},"responses":{"200":{"description":"Small file: `{ path: \"convex\" }`."},"201":{"description":"Upload opened: `path`, `objectId`, `pathname`, `partSizeBytes`, `partCount`, `multipartKey`, `multipartUploadId`, `clientToken`, `validUntil`."},"413":{"description":"The storage pool has no room for this file."},"415":{"description":"Not a media type we take."},"503":{"description":"The private store is not configured on this deployment."}}}},"/api/v2/video-studio/take-lists":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Create a multi-take project","description":"Several saved takes in order, joined at their ends, with spans cut out. Non-destructive and free.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":120}},"required":["title"]}}}},"responses":{"201":{"description":"`listId`."}}}},"/api/v2/video-studio/take-lists/{id}":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"A multi-take project with its joined timeline","description":"`timeline.segments` is the edit list. A mark snaps outward to whole sentences once a take has a transcript; before that its `check` is `no_transcript`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id returned when it was created."}],"responses":{"200":{"description":"Project and timeline."},"404":{"description":"Not found."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Change takes or cuts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id returned when it was created."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["add_take","remove_take","move_take","cut_span","clear_cut"]},"contentId":{"type":"string"},"from":{"type":"integer"},"to":{"type":"integer"},"startMs":{"type":"number"},"endMs":{"type":"number"},"index":{"type":"integer"}},"required":["action"]}}}},"responses":{"200":{"description":"Done."},"400":{"description":"A bad span."},"404":{"description":"Not found."}}}},"/api/v2/media/takes":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Save an upload as a Library draft","description":"Pass `objectId` from a completed large upload, or `storageId` from POST /api/v2/media/upload-url. Free, and safe to retry. A WebM also queues one MP4 copy, which lands as a linked draft.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string","enum":["recorded","uploaded"]},"objectId":{"type":"string"},"storageId":{"type":"string"},"contentType":{"type":"string"},"title":{"type":"string","maxLength":120},"durationMs":{"type":"number"},"hasAudio":{"type":"boolean"}},"required":["origin"]}}}},"responses":{"200":{"description":"Already saved: the same row."},"201":{"description":"`contentId`, `externalId`, `transcodeQueued`, `created`."},"404":{"description":"Not found."},"409":{"description":"The upload has not finished."}}}},"/api/v2/media/large-upload/{id}":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Upload status, for resuming","description":"Includes `missingParts`: the only parts a resuming client still has to send. Never includes a token; renew one with action `token`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id returned when it was created."}],"responses":{"200":{"description":"Status and `missingParts`."},"404":{"description":"Not found."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Record a part, renew the token, or complete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id returned when it was created."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["part","token","complete"]},"partNumber":{"type":"integer","description":"action `part`: 1-based."},"etag":{"type":"string","description":"action `part`: from `uploadPart`."}},"required":["action"]}}}},"responses":{"200":{"description":"part: `{ missing }`. token: `{ clientToken, validUntil }`. complete: `{ objectId, sizeBytes, readUrl }`."},"409":{"description":"Complete with parts missing (`missingParts`), or the upload is no longer open."}}},"delete":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Cancel an upload","description":"Releases its bytes from the storage pool. Refused once a Library item uses the object.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id returned when it was created."}],"responses":{"200":{"description":"Cancelled."},"409":{"description":"A Library item uses it."}}}},"/api/v2/video-studio/projects":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Start a project from a saved take","description":"Takes a Library video saved through POST /api/v2/media/takes. `marks` are moments in ms, stored as cues on its timeline; they propose nothing by themselves. One video has one project, so a retry returns the same one. Free.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string"},"origin":{"type":"string","enum":["recorded","uploaded"]},"title":{"type":"string","maxLength":200},"marks":{"type":"array","maxItems":1000,"items":{"type":"number","minimum":0}}},"required":["contentId","origin"]}}}},"responses":{"200":{"description":"Already existed: `projectId`."},"201":{"description":"Created: `projectId`."},"404":{"description":"That video is not in this brand."}}}},"/api/v2/video-studio/projects/{id}/progress":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"A project's progress","description":"Every step with `status` (not_started, waiting, running, done, skipped, failed, refunded), a wait or time left where known, Embers spent and refunded, and a link to the result. A `queue.position` is counted from the queue, so treat it as approximate. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Steps and totals."},"404":{"description":"Not found."}}}},"/api/v2/video-studio/projects/{id}/quote":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"What a priced step would cost","description":"Lines with a reason, the total and what a re-run costs. No charge inside the studio runs without an accepted quote.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"step","in":"query","required":true,"schema":{"type":"string","enum":["transcribe","analyze","review","render"]}}],"responses":{"200":{"description":"The estimate."},"400":{"description":"Not a priced step, or no length known yet."},"404":{"description":"Not found."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Accept a quote","description":"`embersQuoted` is a ceiling. The server re-prices: if the price rose it answers 409 `quote_changed` and nothing is accepted. Passing the project Ember limit answers 409 `over_cap` until `capConfirmed` is true. Returns a `quoteId`, used once.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"step":{"type":"string","enum":["transcribe","analyze","review","render"]},"embersQuoted":{"type":"integer","minimum":0},"capConfirmed":{"type":"boolean"}},"required":["step","embersQuoted"]}}}},"responses":{"201":{"description":"`quoteId`, `embers`."},"409":{"description":"`quote_changed` or `over_cap`, with `required`."}}}},"/api/v2/video-studio/projects/{id}/transcribe":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Transcribe the project on an accepted quote","description":"Takes a `quoteId` from POST .../quote with step `transcribe`, used once. Same job and price as Library Transcribe, refunded once if it fails. Without an accepted quote it does not run.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string"}},"required":["quoteId"]}}}},"responses":{"200":{"description":"Already running: `jobId`, `existing: true`."},"201":{"description":"`jobId`."},"409":{"description":"No accepted quote."}}}},"/api/v2/video-studio/projects/{id}/sections":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"A project's sections","description":"In order, each with `startMs`, `endMs`, `[wordStart, wordEnd)` into the word timings, its text as transcribed and any decision. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`sections`."},"404":{"description":"Not found."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Section the project from its transcript","description":"Runs by itself after a transcript lands. Same transcript, same sections, so decisions are kept. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Started."},"409":{"description":"No transcript yet."}}}},"/api/v2/video-studio/projects/{id}/analyze":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Run the signal check on an accepted quote","description":"Takes a `quoteId` from POST .../quote with step `analyze`, used once. A re-run on the same file reuses the report at no charge, so `quoteId` is optional then and answers `reused: true`. Refunded once if it fails.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string"}},"required":[]}}}},"responses":{"200":{"description":"Report reused: `reused: true`."},"202":{"description":"Started."},"409":{"description":"No accepted quote."}}}},"/api/v2/video-studio/projects/{id}/flags":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"A project's flags","description":"Opening flags first, then by severity and time. Each states what was found and offers fixes from a closed set. No flag blocks anything, and none carries words to say.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`flags`."},"404":{"description":"Not found."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Decide a flag","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"flagId":{"type":"string"},"option":{"type":"string","enum":["keep","drop","trim","choose_take","cover_card","re_record","clean_audio","clone_patch"]},"reason":{"type":"string","maxLength":500}},"required":["flagId","option"]}}}},"responses":{"200":{"description":"Decided."},"400":{"description":"That flag does not offer that fix."}}}},"/api/v2/video-studio/projects/{id}/board":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"The section board","description":"Sections in play order, flags, timeline markers (warning, success, error, mark, info) and the decisions version. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The board."},"404":{"description":"Not found."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Change a decision","description":"By `action`: `section` (`sectionId`, `kind`, `ranges`), `reorder` (`sectionId`, `toIndex`), `transition` (`sectionId`, `transitionId`, `ms`), `undo`. Versioned, with who and when. Free. Nothing here is refused because of a flag.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["section","reorder","transition","undo"]}},"required":["action"]}}}},"responses":{"200":{"description":"Done."},"400":{"description":"A range outside the section, or an unknown transition."}}}},"/api/v2/video-studio/projects/{id}/auto":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Auto-edit suggestions","description":"The suggestion items the auto pass wrote (`origin: auto`; step, kind, status suggested|accepted|removed|swapped, atMs, spanMs, summary, payload), the latest `autoRun` (steps that ran or were skipped and why, and whether the Edited render may start by itself: with the default auto-spend ceiling of 0 it always asks) and the brand's resolved auto profile. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`suggestions`, `autoRun`, `profile`, `transitionIds`."},"404":{"description":"Not found."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Run the auto pass, or decide a suggestion","description":"No `action` (or `run`): runs the brand's enabled auto steps in order (sectioning, dead-air trims at sentence boundaries, retake picks, 0.4-0.7 s dissolves, room tone, loudness at -16 LUFS / -1 dBTP by default, background preset, motion pack) and writes suggestions; it replaces items not yet decided and keeps decided ones. It never edits the master and never starts a render. `accept` writes a board decision (versioned, undoable) or sets the join; `remove` drops the item; `swap` picks another transition (`transitionId`, `ms`) or preset (`presetId`). Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["run","accept","remove","swap"],"description":"Default run."},"suggestionId":{"type":"string","description":"For accept, remove, swap."},"transitionId":{"type":"string","description":"Swap a transition: cut or crossfade."},"ms":{"type":"number","minimum":0,"maximum":10000,"description":"Swap a dissolve length; clamped to 400-700."},"presetId":{"type":"string","maxLength":100,"description":"Swap a background preset or motion pack (effect catalog id)."}},"required":[]}}}},"responses":{"200":{"description":"Decided: `status`."},"202":{"description":"Run queued: `queued`, `projectId`."},"400":{"description":"`invalid_body`, or nothing to swap."},"404":{"description":"Not found in this brand."},"409":{"description":"`already_decided`, `conflict` (the section is dropped) or `gone` (the section left the board)."}}}},"/api/v2/video-studio/projects/{id}/plan":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Compile the decisions into a plan","description":"Whole sentences only. A kept range grows to the sentence around it, reported in `adjustments`. A reorder that splits a sentence answers `ok: false`. Free; nothing renders here.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"string","enum":["raw","cut","full"]}},"required":["profile"]}}}},"responses":{"200":{"description":"The summary, or `ok: false` with `errors`."}}}},"/api/v2/video-studio/projects/{id}/render":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"A project's versions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`versions`: profile, status, the draft once ready, any refund."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Make a version","description":"`{ profile: \"raw\" }`: no picture or sound change, free; an MP4 source needs no job. `{ quoteId }`: the Edited version: POST .../plan first, then a quote with step `render`, charged at the combine rate. Each makes a new linked draft; the original is untouched. Refunded once if it fails. Full is not available yet.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string"},"profile":{"type":"string","enum":["raw"]}},"required":[]}}}},"responses":{"200":{"description":"Raw already exists."},"202":{"description":"Queued: `versionId`."},"409":{"description":"`no_plan`, `plan_stale` or `no_accepted_quote`."}}}},"/api/v2/video-studio/projects/{id}/cuts":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"A project's saved versions and its final cut","description":"`cuts`: every saved version, newest first (draft or final, its name, status, `isFinal`, `isOpen`). `finalCut`: THE final cut, the one campaigns and approvals use, with its rendered draft (`contentId`). With `diff` (a cut id, or empty for the board as it stands) also returns what it changed since the auto cut. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"diff","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"`cuts`, `finalCut`, and `diff: { items, total }` when asked."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Save a draft, save the final cut, or reopen a version","description":"`{ action: \"save_draft\", name? }` stores the board as it stands; free, nothing renders. `{ action: \"save_final\", quoteId, name? }` stores it and renders it like POST .../render (POST .../plan, then a quote with step `render`, estimate first); once the render is ready it becomes the final cut, one at a time, and the earlier final is kept. `{ action: \"reopen\", cutId }` puts a version back on the board (each change can be undone); the next save is a new version.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["save_draft","save_final","reopen"]},"name":{"type":"string","maxLength":200},"quoteId":{"type":"string"},"cutId":{"type":"string"}},"required":["action"]}}}},"responses":{"200":{"description":"Reopened: `changes`."},"201":{"description":"Draft saved: `cutId`, `number`, `name`."},"202":{"description":"Final cut rendering: `cutId`, `versionId`."},"409":{"description":"`too_many_versions`, `no_sections`, `no_plan`, `plan_stale` or `no_accepted_quote`."}}}},"/api/v2/video-studio/take-lists/{id}/render":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Get a multi-take project ready to render","description":"Refused with 409 `unchecked_cuts` while a cut sits on a take with no transcript: that cut could land inside a sentence. Otherwise returns the `projectId` to quote and render. Nothing is charged here.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`projectId`, `outputMs`."},"409":{"description":"`unchecked_cuts` with `takeIds`, `no_takes` or `unknown_length`."}}}},"/api/v2/video-studio/projects/{id}/review":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Run the AI production review on an accepted quote","description":"Adds flags with a reason: legal, financial or health claims, profanity in the opening, personal data, structure, possible section titles. It writes nothing for you to say and blocks nothing. An aid, not a verdict. The share that fails is refunded; rule flags stay.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string"}},"required":["quoteId"]}}}},"responses":{"202":{"description":"Started: `reviewId`."},"409":{"description":"`no_sections` or `no_accepted_quote`."}}}},"/api/v2/video-studio/templates/poem/render":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Render a verbatim poem into drafts","description":"Supply exactly one of text or contentId. Stock shots are selected per line group unless supplied. Brand settings supply the wordmark, handle, accent and end-card line. Rendering runs on the hive worker using ffmpeg while HyperFrames is unavailable. Each requested format becomes one draft with no destinations. No AI rewriting, approval, scheduling or publishing. Music is normalized to -16 LUFS. Poll each returned job at /api/v2/generate/status/{jobId}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string"},"text":{"type":"string","maxLength":5000},"title":{"type":"string","maxLength":120},"author":{"type":"string","maxLength":100},"year":{"type":"string","pattern":"^\\d{4}$"},"brandId":{"type":"string"},"musicTrackId":{"type":"string","description":"An existing, unarchived track in this brand. Omit for silent video."},"outputs":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["vertical","carousel","text"]}},"shots":{"type":"array","maxItems":8,"description":"One clip per line group returned by verbatim chunking; omitted means automatic free stock search.","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"provider":{"type":"string","enum":["pexels","pixabay"]},"credit":{"type":"string"},"inSeconds":{"type":"number","minimum":0,"maximum":600,"default":0},"focusX":{"type":"number","minimum":0,"maximum":1,"default":0.5}},"required":["url","provider","credit"]}}},"required":["title","author"]}}}},"responses":{"202":{"description":"jobs: [{output, jobId}], optional textContentId. The text draft exists immediately; media drafts are created on completion."},"400":{"description":"Invalid request."},"403":{"description":"Brand scope is forbidden."},"404":{"description":"Source not found in this brand."},"422":{"description":"Poem, footage or music cannot be rendered."},"429":{"description":"Rate limit or open-render cap."}}}},"/api/v2/video-studio/templates/step-series/render":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Render a numbered step series (Record Room) into drafts","description":"Preset `record-room` by default. Each step becomes an auto-numbered \"STEP 0N\" scene: brand chip, breadcrumb, 1–3 line headline, a card with up to 2 icons and 3 lines, and a progress bar. Optional look: hide the STEP pill (`showStepLabel: false`), add a CTA end card (`endCard`), burn in an AI label (`aiLabel`, required when a step is `aiGenerated`) and pick heading/body fonts (`brand` uses the primary font file in Brand assets). Outputs: `vertical` (one 9:16 Short with every step), `per-step` (one 9:16 Short per step), `carousel-square` (1:1) and `carousel-portrait` (4:5) cards. Brand name, colours and logo come from the brand profile and Brand assets; numbering continues from the brand's last series unless `startNumber` is given. Rendering runs on the hive worker. Every output is a draft with no destinations; nothing is approved, scheduled or posted. Poll each returned job at /api/v2/generate/status/{jobId}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"presetId":{"type":"string","default":"record-room"},"series":{"type":"string","maxLength":40},"category":{"type":"string","maxLength":40},"startNumber":{"type":"integer","minimum":1,"maximum":99},"brandId":{"type":"string"},"musicTrackId":{"type":"string","description":"An existing, unarchived track in this brand. Omit for silent video."},"outputs":{"type":"array","minItems":1,"maxItems":4,"uniqueItems":true,"items":{"type":"string","enum":["vertical","per-step","carousel-square","carousel-portrait"]}},"steps":{"type":"array","minItems":1,"maxItems":12,"items":{"type":"object","properties":{"headline":{"type":"string","maxLength":60,"description":"Shown uppercase, auto-fit to 1–3 lines."},"lines":{"type":"array","maxItems":3,"items":{"type":"string","maxLength":28}},"icons":{"type":"array","maxItems":2,"description":"Omitted means the preset icons.","items":{"type":"object","properties":{"kind":{"type":"string","enum":["vinyl","ring","check","spark"]},"tone":{"type":"string","enum":["a","b"]}},"required":["kind"]}},"background":{"type":"object","properties":{"kind":{"type":"string","enum":["image","video"]},"url":{"type":"string","format":"uri"},"provider":{"type":"string","enum":["pexels","pixabay"]},"credit":{"type":"string"},"focusX":{"type":"number","minimum":0,"maximum":1},"inSeconds":{"type":"number","minimum":0}},"required":["kind","url","provider","credit"]},"aiGenerated":{"type":"boolean","description":"This step's imagery is AI-generated: the AI label is burned in and the drafts are marked AI-generated."}},"required":["headline"]}},"showStepLabel":{"type":"boolean","description":"false hides the \"STEP 0N\" pill. Default: brand defaults, then the preset (shown)."},"endCard":{"type":"object","properties":{"headline":{"type":"string","minLength":1,"maxLength":40},"cta":{"type":"string","minLength":1,"maxLength":28},"url":{"type":"string","maxLength":40,"description":"Shown as text, e.g. example.com/shop."}},"required":["headline","cta"]},"aiLabel":{"oneOf":[{"type":"boolean"},{"type":"string","minLength":1,"maxLength":40}],"description":"Burned-in AI label. A string sets the text; true uses the brand's saved label or \"AI-generated imagery\"; false turns it off (not allowed when any step is aiGenerated)."},"fonts":{"type":"object","properties":{"heading":{"type":"string","enum":["inter","cormorant","jetbrains-mono","brand"]},"body":{"type":"string","enum":["inter","cormorant","jetbrains-mono","brand"]}},"required":["heading","body"]}},"required":["steps"]}}}},"responses":{"202":{"description":"jobs: [{output, jobId}]. Drafts are created when each job completes."},"400":{"description":"Invalid request."},"403":{"description":"Brand scope is forbidden."},"422":{"description":"Copy, background or music cannot be rendered."},"429":{"description":"Rate limit or open-render cap."}}}},"/api/v2/video-studio/templates/motion-ad-from-card/render":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Render a motion ad from a Library card","description":"Template `motion-ad-from-card`: one Library image becomes a 6-15 s ad, hook (push-in on the card) -> 0-3 body beats (pans with the beat text) -> CTA end card in the brand color with the CTA and the link host. 9:16 unless `aspect` says 1:1 or 16:9. The text is used as given, never rewritten. Saved as a new draft in the card's brand, labelled `format:motion-ad` and `source:template`; nothing is posted and the card is unchanged. Free; open renders per person are capped. Poll GET /api/v2/generate/status/{jobId}: `resultContentId` is the new draft.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string","description":"The card: a Library image."},"hook":{"type":"string","minLength":1,"maxLength":500},"body":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":500},"description":"Up to 3 beats are used; blanks are dropped."},"cta":{"type":"string","minLength":1,"maxLength":500},"ctaUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"http(s) link; its host is shown on the end card."},"aspect":{"type":"string","enum":["9:16","1:1","16:9"]},"brandColor":{"type":"string","maxLength":20,"description":"#RRGGBB; defaults to the brand profile color."},"textColor":{"type":"string","maxLength":20,"description":"#RRGGBB."}},"required":["contentId","hook","cta","ctaUrl"]}}}},"responses":{"202":{"description":"Queued: `jobId`, `status`, `durationMs`, `aspect`."},"400":{"description":"`invalid_body` with `field`."},"404":{"description":"That card is not in this brand."},"422":{"description":"`invalid_input` with `field` (for example the card is not an image, or the link is not http(s))."},"429":{"description":"Rate limited, or `too_many_renders`."}}}},"/api/v2/video-studio/segment-ads":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"List a brand's ad segments","description":"One segment per confirmed offer that names an audience: its pains, outcomes, proof and the brand website (the default CTA link). Ranked shops/commerce first, local services second (`tier`, `rank`; tiers are config). Read-only, free.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands). Required for an account-wide key."}],"responses":{"200":{"description":"`segments`."},"404":{"description":"Brand not found."},"422":{"description":"`brandId` missing."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Generate an ad for a brand segment","description":"Builds the segment script (hook, persona, offer, proof, CTA beats) from the owner's own words, or checks the `beats` the owner edited: each beat is claims-checked and figures must come from the segment's offer, outcomes or proof. Without `render` nothing is stored, and `variants` proposes the ad per network (ad text cut to the network cap, planned length, ad-cut lint, `ready`); nothing is booked. With `render: true` (write scope), `contentId` (a Library card of the same brand) and a clean script, a free silent motion ad is queued; poll GET /api/v2/generate/status/{jobId}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Required for an account-wide key."},"segmentId":{"type":"string","description":"A segment id from GET."},"beats":{"type":"array","maxItems":8,"items":{"type":"object"},"description":"`{ role: hook|persona|offer|proof|cta, text }`, hook first and CTA last. Omit to use the generated script."},"contentId":{"type":"string","description":"The card, a Library image of this brand. Needed to render."},"ctaUrl":{"type":"string","maxLength":2048,"description":"Defaults to the brand website."},"aspect":{"type":"string","enum":["9:16","1:1","16:9"]},"networks":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string"},"description":"Network ids for the `variants` proposals. Default: the configured list."},"render":{"type":"boolean","description":"Queue the render. Default false: preview only."}},"required":["segmentId"]}}}},"responses":{"200":{"description":"Preview: `segment`, `script`, `issues`, `claims`, `ctaUrl`, `variants`."},"202":{"description":"Queued: `jobId`, `status`, `durationMs`, `aspect`, `voiced`."},"404":{"description":"Segment or card not found."},"422":{"description":"`script_not_clean` (with `issues` and `claims`), or `invalid_input`."}}}},"/api/v2/video-studio/segment-ads/voice":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Voice a rendered segment ad","description":"Speaks the segment script over the silent draft a segment-ad render made, through the existing voiceover pipeline: a stock voice (default openai/tts-1:onyx) or the owner's voice clone, with the brand pronunciation lexicon. The script is rebuilt (or `beats` re-checked) and must be clean. Captions are not burnt in again. Speech longer than the configured share of the ad is refused (the voice is never sped up). Costs the usual voiceover Embers (speech per 1,000 characters plus mixing per started minute), charged when the mix is queued and refunded if it fails. Saves a new voiced draft; nothing is posted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Required for an account-wide key."},"segmentId":{"type":"string","description":"The segment the draft was made for."},"beats":{"type":"array","maxItems":8,"items":{"type":"object"},"description":"The beats used for the render, if they were edited."},"contentId":{"type":"string","description":"The silent draft: `resultContentId` of the segment-ad render."},"voice":{"type":"object","description":"`{ kind: \"stock\", stockVoiceId }` or `{ kind: \"clone\", cloneId }`. Default: the default stock voice."},"fallbackStockVoiceId":{"type":"string","description":"Clone only: the stock voice to use if the voice server is down."}},"required":["segmentId","contentId"]}}}},"responses":{"202":{"description":"Queued: `jobId`, `status: queued`, `embers`, `voice`, `text`, `speechSeconds`, `maxSpeechSeconds`. Or (clone) `speechJobId`, `status: speaking`."},"402":{"description":"Not enough Embers."},"404":{"description":"Segment or draft not found."},"422":{"description":"`script_not_clean`, `speech_too_long` (with `speechSeconds`, `maxSpeechSeconds`), or `invalid_input`."},"429":{"description":"Rate limited, or a voice clone limit."}}}},"/api/v2/video-studio/templates/teardown/plan":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Plan a teardown film from a 3D model","description":"Teardown Studio. Send `model` (base64 STL, 3MF or GLB, up to 3 MB inline by default) to get its parts list, a default `teardown/1` plan built from part count and bounding boxes (hold, explode, label the biggest parts, slow-motion, reassemble, reveal, brand end card; 16:9 and 9:16), and the render estimate. Or send an edited `plan` (instead of a model) to check it against the limits, clean it, and re-estimate. Read-only: nothing is stored, rendered or charged. A model whose `status` is not `physical` is labelled \"3D render\" in the film.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Base64 of the model file (STL, 3MF or GLB). Send this or `plan`."},"fileName":{"type":"string","maxLength":200,"description":"Helps detect the format, e.g. caddy.stl."},"title":{"type":"string","maxLength":200,"description":"Film title and end-card headline."},"status":{"type":"string","enum":["render","prototype","physical"],"description":"Is this a real, made object? Anything but physical gets a \"3D render\" label."},"engraving":{"type":"boolean","description":"Show the NAME engraving placeholder on the reveal."},"brandName":{"type":"string","maxLength":100},"accent":{"type":"string","description":"#RRGGBB end-card accent."},"names":{"type":"object","description":"Part id -> name, e.g. { \"p0\": \"Lid\" }."},"plan":{"type":"object","description":"An edited teardown/1 plan (from an earlier call). Send this or `model`."}},"required":[]}}}},"responses":{"200":{"description":"`model` { format, bounds, triangles, parts [{ id, name, triangles, bounds }] } (model input only), `plan` (teardown/1), `estimate` { outputs [{ aspect, width, height, frames }], durationMs, fps, totalFrames, renderSeconds, embers: 0, renderBadge }."},"400":{"description":"`invalid_body` with `field` (send exactly one of model / plan)."},"413":{"description":"`model_too_large`: use the Teardown Studio page for bigger files."},"422":{"description":"`invalid_model` with `code` and `message`, or `invalid_plan` with `errors`."},"429":{"description":"Rate limited."}}}},"/api/v2/video-studio/ad-cut/lint":{"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"summary":"Lint an ad cut against the ad-cut rules","description":"Checks a described cut: join count (warn), joins only at a rest point, no cut inside a caption or its fade, one caption layer, no audio dip at a join, exactly one ending, and the network window (length, aspect, ad text). The rules are config; the platform limits are a floor. A rule with no signal to check it comes back `unchecked`. The lint reads the cut as described, not a rendered file. With `contentId` (write scope) the result is kept for that draft and the draft's own text is the ad text: a `format:ad` video draft is booked or filed as an ad only once its latest lint for the network passes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"network":{"type":"string","description":"tiktok, x, pinterest, reddit, or a configured network."},"segments":{"type":"array","maxItems":100,"items":{"type":"object"},"description":"In order: takes `{ sourceId, inMs, outMs, includesEnding? }` or `{ kind: \"end_card\", durationMs }`."},"joins":{"type":"array","maxItems":200,"items":{"type":"number"},"description":"Extra cut points inside segments, output ms."},"captions":{"type":"array","maxItems":200,"items":{"type":"object"},"description":"`{ startMs, endMs, text?, layer?, fadeInMs?, fadeOutMs? }` in output ms. Omit when unknown; [] for none."},"audioEnvelope":{"description":"Output-time `[{ atMs, db }]`, per-source `{ sourceId: [{ atMs, db }] }`, or null for no audio."},"signals":{"type":"object","description":"Per source: `{ motion?: [{ atMs, energy }], envelope?: [{ atMs, db }] }`, in source ms."},"aspect":{"description":"For example \"9:16\", or `{ width, height }`."},"adText":{"type":"string","maxLength":5000,"description":"Ignored with contentId (the draft text is used)."},"contentId":{"type":"string","description":"Keep the result for this draft (write scope)."}},"required":["network","segments"]}}}},"responses":{"200":{"description":"`network`, `verdict` (pass|fail), `findings` [{ rule, severity, atMs?, message, fix, unchecked? }], `durationMs`, `joinCount`, and `lintId` when kept."},"400":{"description":"`invalid_body`."},"403":{"description":"contentId without the write scope."},"404":{"description":"That draft is not in this brand."},"422":{"description":"`invalid_cut` with a message."}}}},"/api/v2/posts/{id}":{"get":{"tags":["API v2"],"summary":"Get a scheduled post's first comments","description":"The post (status, scheduledAt, platforms, `platformAccounts` (platform → the account each leg posts from), its draft `contentId`) and, while it is scheduled, the first comment each platform will publish (`firstComments`, read from the platform scheduler; \"\" = none) and whether it can be changed now (`editable`, `blocked`).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}."}],"responses":{"200":{"description":"The post"},"401":{"description":"Unauthorized"},"404":{"description":"Not found or not visible to this key"}}},"patch":{"tags":["API v2"],"summary":"Edit or reschedule a scheduled post (caption, first comments, time)","description":"Metadata-only PATCH with labels and/or instanceLabels edits internal labels even after publishing, without contacting the scheduler. labelMode add appends atomically. GET returns both sets. Send separately from booking edits. Changes what a SCHEDULED post will publish, keeping its slot, accounts, platform options (YouTube title/visibility/playlist, …), labels / experiment and draft. `text` / `platformText` change the caption (saved on the post's draft first, as PATCH /api/v2/content/{id} takes them; the post is then rebuilt from the draft with the caption watermark, credits and watermark rules). `firstComment` changes per-platform first comments (LinkedIn, Facebook, Instagram, Threads, YouTube). A body with only `firstComment` / `applyAutoFirstComment` sends the booked caption and media back untouched. `scheduledAt` (ISO 8601 with a timezone, more than 5 minutes ahead, sent on its own) moves the post to a new time in place: same booking id, caption, media, accounts and options; its posting-queue item follows. Answers `status: \"rescheduled\"` and the new `scheduledAt`. `switchAccounts` ({ \"facebook\": \"<accountId>\" }, sent on its own) moves that platform leg to another healthy connected account of the post's brand on the same platform, in place: the other legs, caption, media, slot and options go back exactly as booked (nothing is rebuilt from the draft, so a post made without one works too). Refused (409) unless the booking and every leg are still pending; 422 when the account is not in the brand, is another platform, or is not healthy. Answers `status: \"switched\"` (or `unchanged` on a repeat). On a post HELD for review (`pending_review`, `review_held`, `missed_review`; FFE-1597) `switchAccounts` rewrites flayr's post and the review's stored request only (no booking exists to edit): it never approves, the post stays held and goes out on the new accounts when approved. A platform not on the post, or on more than one account, is refused (422). Add `dryRun: true` to preview (`status: \"would_switch\"`, nothing written). Answers { status: switched | unchanged | would_switch, postStatus, platformAccounts, from, to, reviewRequestUpdated }; each switch writes an audit entry. `applyAutoFirstComment: true` adds the brand's auto first comment (its variants and tracked {link}) on platforms where the post has none; an explicit comment always wins. HOW: the platform scheduler's update endpoint first; if it will not apply the edit, the post is replaced at the same slot (validated first; the old booking removed before the new one is made, with an idempotency key; the original re-booked if the edit is refused) and `status` is `rebooked` with the new `postId`. Some scheduled YouTube uploads cannot be removed: then every other platform is updated and YouTube keeps its booked version (see `warnings`). Only this post changes, even when the draft was booked more than once. Refused (409) while the post is posting, posted, within 5 minutes of its slot, made without a draft, or in a brand whose scheduled posts require review. Repeating the same first-comment edit returns `unchanged`. Agency+ plan; `publish` scope (or admin); an editor role on the draft.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"text":{"type":"string","minLength":1,"maxLength":10000,"description":"The caption (every platform without its own)."},"platformText":{"type":"object","nullable":true,"additionalProperties":{"type":"string","nullable":true},"description":"Per-platform captions, merged into the draft's: { \"linkedin\": \"…\" } sets one, null / \"\" clears it; null clears them all."},"instanceLabels":{"type":"array","maxItems":20,"description":"Internal labels per platform/account instance. An array of {platform, accountId?, labels}; accountId is the Zernio connected account id. Omit accountId when unknown. instanceKey is derived as canonical platform + \":account:\" + URL-encoded account id, or \":pending\" when unknown (twitter canonicalizes to x). Replaces the instance set when editing; [] clears it. Never published.","items":{"type":"object","required":["platform","labels"],"additionalProperties":false,"properties":{"platform":{"type":"string"},"accountId":{"type":"string","maxLength":200},"labels":{"type":"array","maxItems":30,"items":{"type":"string"}}}}},"labelMode":{"type":"string","enum":["set","add"],"description":"Default set. add atomically appends labels to the post and matching instances; other instances stay unchanged."},"firstComment":{"type":"object","additionalProperties":false,"minProperties":1,"description":"The first comment the post publishes, per platform: a string sets it, null or \"\" removes it; platforms not named keep theirs. X and Bluesky have no first comment at the platform scheduler and are refused (422). A Facebook / Instagram Story never gets one. flayr's own \"Posted with flayr.social\" line on a comment is kept. Also saved on the post's draft, so a later edit never puts the old one back.","properties":{"linkedin":{"type":"string","nullable":true,"maxLength":1250},"facebook":{"type":"string","nullable":true,"maxLength":8000},"instagram":{"type":"string","nullable":true,"maxLength":2200},"threads":{"type":"string","nullable":true,"maxLength":500},"youtube":{"type":"string","nullable":true,"maxLength":10000}}},"applyAutoFirstComment":{"type":"boolean","description":"Add the brand's auto first comment where the post has none."},"scheduledAt":{"type":"string","format":"date-time","description":"Move the post to this time (ISO 8601 with Z or an offset, e.g. \"2026-11-19T15:00:00Z\"); more than 5 minutes in the future. Send it on its own: no other field with it."},"switchAccounts":{"type":"object","minProperties":1,"maxProperties":10,"additionalProperties":{"type":"string","minLength":1},"description":"Move these platform legs to other accounts, in place: { \"facebook\": \"<accountId>\" }. Each account must be a healthy connection of the post's brand on that platform. Send it on its own (only `dryRun` may go with it)."},"dryRun":{"type":"boolean","description":"With `switchAccounts` on a post held for review: preview the switch (status \"would_switch\"), nothing written. Refused (409) on a scheduled post."},"removePlatforms":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Platform ids to drop from this booking (e.g. a duplicate [\"tiktok\"]). Each must be on the post; dropping every platform is refused (use DELETE). The booking is rebuilt from the draft."},"labels":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"},"description":"Sets this post's own labels ([] or null clears; labelMode add appends), e.g. [\"repost:evergreen\"]. flayr metadata: sent alone it never touches the booking (status \"labeled\") and works on posted posts too. With booking edits, metadata is saved after a successful edit. Normalized \"key:value\" labels (keys and values are lower-cased, spaces become \"-\"). Linked keys: campaign:<media campaign id>, experiment:<experiment id> (+ variant:<name> or the experiment's compareKey), type:<post type> (short, long-form, carousel, image, text, reel, story, poem, timelapse…). Free keys work too: cut:opus, lane:tech, parent:pantheon-part-1, ab:<pair id> (an A/B pair). Labels are copied onto every post made from the draft, and compared in GET /api/v2/analytics/experiments.","nullable":true}}}}}},"responses":{"200":{"description":"Updated, re-booked, rescheduled, switched, unchanged, or labeled","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The post (unchanged)."},"postId":{"type":"string","description":"The booking at the platform scheduler — a new id after a re-book."},"status":{"type":"string","enum":["updated","rebooked","rescheduled","switched","would_switch","unchanged","labeled"],"description":"updated: changed in place. switched: the `switchAccounts` legs moved to their new accounts in place (a held post: flayr's row and review request). would_switch: a held-post `dryRun` preview. rebooked: replaced at the same slot (same accounts, options, labels and draft). rescheduled: moved to `scheduledAt` in place. unchanged: nothing to change (a repeat of the same edit). labeled: internal metadata saved without changing the booking."},"labels":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"},"description":"Normalized \"key:value\" labels (keys and values are lower-cased, spaces become \"-\"). Linked keys: campaign:<media campaign id>, experiment:<experiment id> (+ variant:<name> or the experiment's compareKey), type:<post type> (short, long-form, carousel, image, text, reel, story, poem, timelapse…). Free keys work too: cut:opus, lane:tech, parent:pantheon-part-1, ab:<pair id> (an A/B pair). Labels are copied onto every post made from the draft, and compared in GET /api/v2/analytics/experiments."},"instanceLabels":{"type":"array","maxItems":20,"description":"Internal labels per platform/account instance. An array of {platform, accountId?, labels}; accountId is the Zernio connected account id. Omit accountId when unknown. instanceKey is derived as canonical platform + \":account:\" + URL-encoded account id, or \":pending\" when unknown (twitter canonicalizes to x). Replaces the instance set when editing; [] clears it. Never published.","items":{"type":"object","required":["platform","labels"],"additionalProperties":false,"properties":{"platform":{"type":"string"},"accountId":{"type":"string","maxLength":200},"labels":{"type":"array","maxItems":30,"items":{"type":"string"}}}}},"message":{"type":"string"},"scheduledAt":{"description":"The slot: ms since epoch, or the ISO 8601 date-time after a reschedule.","nullable":true},"switchAccounts":{"type":"object","additionalProperties":{"type":"string"},"description":"After an account switch: platform → the account that leg now posts from."},"postStatus":{"type":"string","description":"Held `switchAccounts`: the post's status, unchanged (it stays held)."},"platformAccounts":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"accountId":{"type":"string"}}},"description":"Held `switchAccounts`: each leg's account after the switch (or the preview)."},"from":{"type":"object","additionalProperties":{"type":"string"},"description":"Held `switchAccounts`: platform → the account it moved off."},"to":{"type":"object","additionalProperties":{"type":"string"},"description":"Held `switchAccounts`: platform → the account it moved to."},"reviewRequestUpdated":{"type":"boolean","description":"Held `switchAccounts`: the review's stored request named the old account and was (or would be) rewritten."},"dryRun":{"type":"boolean"},"queueItemMoved":{"type":"boolean","description":"After a reschedule: the posting-queue item booked for the post took the new slot too."},"platforms":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"},"description":"e.g. YouTube kept its booked version because its upload cannot be replaced."},"autoFirstComment":{"type":"array","items":{"type":"string"},"description":"Platforms that got the brand's auto first comment."}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Missing publish scope, plan, or edit role"},"404":{"description":"Not found or not visible to this key"},"409":{"description":"Not changeable now (posting / posted / within 5 minutes / no draft / review required / being changed)"},"422":{"description":"Validation error"},"429":{"description":"Rate or quota limit"},"502":{"description":"The platform scheduler refused or failed; the body says whether the original is still booked"},"503":{"description":"Review settings could not be read (nothing changed)"}}},"delete":{"tags":["API v2"],"summary":"Cancel a scheduled post","description":"Removes a SCHEDULED post from the platform scheduler and marks it cancelled in flayr (the draft stays). Repeating it on a cancelled post returns 200 with `alreadyCancelled: true`. Refused (409) while it is posting, posted or within 5 minutes of its slot, or when the platform scheduler will not remove it (some scheduled YouTube uploads cannot be deleted — it stays scheduled). Agency+ plan; `publish` scope (or admin); an editor role on the draft.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}."}],"responses":{"200":{"description":"{ id, status: \"cancelled\", alreadyCancelled? }"},"401":{"description":"Unauthorized"},"403":{"description":"Missing publish scope, plan, or edit role"},"404":{"description":"Not found or not visible to this key"},"409":{"description":"Not cancellable now, or the platform scheduler refused (still scheduled)"},"502":{"description":"The platform scheduler did not confirm; check the post before retrying"}}}},"/api/v2/posts/{id}/analytics":{"get":{"tags":["API v2"],"summary":"One post's full analytics, per network, with video drop-off","description":"Every metric each network reports for the post (null = not reported, never 0), the second-by-second retention curve with the hook window and the point where half the viewers left for videos, the reach → engaged → clicked → visited funnel for other posts, history from the scheduled snapshots, and spend and cost per result for boosts made from the post (Ads plans). Needs the read scope and Pro+.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Post id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Post analytics","content":{"application/json":{"schema":{"type":"object","properties":{"postId":{"type":"string"},"brandId":{"type":"string","nullable":true},"status":{"type":"string"},"publishedAt":{"type":"number","nullable":true},"excerpt":{"type":"string"},"url":{"type":"string","description":"The post page in flayr."},"networks":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"label":{"type":"string"},"metrics":{"type":"object","description":"Every per-post metric. watchThroughPct, completionRate and skipRate are percents (0-100); avgWatchTimeMs is milliseconds.","properties":{"impressions":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"reach":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"views":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"avgWatchTimeMs":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"watchThroughPct":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"completionRate":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"skipRate":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"likes":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"comments":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"shares":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"saves":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"reposts":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"replays":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"profileVisits":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"follows":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"linkClicks":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."}}},"note":{"type":"string","nullable":true,"description":"What this network does not report, and why."},"delayHours":{"type":"number","description":"Typical hours until the network's numbers settle (config)."},"settling":{"type":"boolean","description":"Younger than delayHours: numbers may still change."},"syncStatus":{"type":"string"},"fetchedAt":{"type":"number","description":"Epoch ms of the last scheduled fetch."},"isVideo":{"type":"boolean"},"watchStatus":{"type":"string","nullable":true,"description":"Watch data state, e.g. `scope_missing` = reconnect YouTube with its Analytics scope."},"retentionSupported":{"type":"boolean"},"retention":{"type":"object","nullable":true,"description":"Video only. null = no curve reported (yet), or the network has none (see retentionSupported).","properties":{"basis":{"type":"string","enum":["seconds","ratio"],"description":"`ratio` = x is the share of the video (0-1), as YouTube reports it."},"points":{"type":"array","items":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number","description":"Share of starting viewers still watching."}}}},"durationSeconds":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"hookSeconds":{"type":"number","description":"The hook window marked on the curve (config, default 3)."},"hookRetention":{"type":"number","nullable":true,"description":"Share still watching at the end of the hook window."},"dropOffShare":{"type":"number","description":"The share of starting viewers that defines the drop-off point (config, default 0.5 = half)."},"dropOffAt":{"type":"number","nullable":true,"description":"Where that share had left, in the curve's x units."},"dropOffSeconds":{"type":"number","nullable":true,"description":"The same point in seconds, when the length is known."},"avgViewDurationSeconds":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."}}},"funnel":{"type":"array","nullable":true,"description":"Non-video posts only: reach (or impressions) → engaged → clicked → visited your site → converted.","items":{"type":"object","properties":{"key":{"type":"string","enum":["reach","engaged","clicked","visited","converted"]},"label":{"type":"string"},"value":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"fromPrevious":{"type":"number","nullable":true,"description":"Share of the previous step (0-1)."}}}},"history":{"type":"array","description":"The scheduled snapshots (48h, 7d, 30d after publish) and the latest fetch.","items":{"type":"object","properties":{"window":{"type":"string","enum":["48h","7d","30d","latest"]},"capturedAt":{"type":"number"},"metrics":{"type":"object","description":"Every per-post metric. watchThroughPct, completionRate and skipRate are percents (0-100); avgWatchTimeMs is milliseconds.","properties":{"impressions":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"reach":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"views":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"avgWatchTimeMs":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"watchThroughPct":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"completionRate":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"skipRate":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"likes":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"comments":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"shares":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"saves":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"reposts":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"replays":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"profileVisits":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"follows":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"linkClicks":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."}}}}}}}}},"pending":{"type":"array","description":"Networks with no numbers fetched yet.","items":{"type":"object","properties":{"platform":{"type":"string"},"label":{"type":"string"}}}},"totals":{"type":"object","description":"Counts summed over the networks that report them; rates and averages are per network only.","properties":{"impressions":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"reach":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"views":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"avgWatchTimeMs":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"watchThroughPct":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"completionRate":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"skipRate":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"likes":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"comments":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"shares":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"saves":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"reposts":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"replays":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"profileVisits":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"follows":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"linkClicks":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."}}},"paid":{"type":"array","items":{"type":"object","properties":{"campaignId":{"type":"string"},"platform":{"type":"string"},"status":{"type":"string"},"objective":{"type":"string","nullable":true},"currency":{"type":"string"},"spendMinor":{"type":"integer","nullable":true,"description":"Spend in minor units (cents)."},"resultLabel":{"type":"string","description":"What counts as a result for the objective (ThruPlays, Link clicks, People reached, Clicks)."},"results":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"costPerResultMinor":{"type":"integer","nullable":true},"impressions":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."},"reach":{"type":"number","nullable":true,"description":"null = the network does not report it (or not yet)."}}}},"hookSeconds":{"type":"number"},"dropOffShare":{"type":"number"},"notReported":{"type":"string","description":"The label shown for a null metric (config, default \"Not reported\")."},"generatedAt":{"type":"number"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan has no analytics"},"403":{"description":"The key lacks the read scope"},"404":{"description":"Not found (or another brand)"},"429":{"description":"Rate limited"}}}},"/api/v2/analytics/videos":{"get":{"tags":["API v2"],"summary":"Video and reel explorer: length against watch-through, sections, hook board","description":"Every video post in the timeframe as one point per network, with length, watch-through, reach, average watch time, engagement rate, hook retention and end retention (null = not reported, never 0). Short-form and long-form sections compare this period with the previous one of the same length (medians, with how many videos reported each). The hook board groups videos by `hook:` and `hook-template:` labels and names the hook that holds viewers through the first seconds and the one that holds them to the end. Needs the read scope and Pro+.","security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"description":"Timeframe in days; snaps to the configured timeframes (default 30).","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Video explorer","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"days":{"type":"integer"},"timeframesDays":{"type":"array","items":{"type":"integer"}},"metrics":{"type":"array","items":{"type":"string","enum":["watchThroughPct","reach","avgWatchTimeMs","engagementRate","views","hookRetention","endRetention"]}},"defaultMetric":{"type":"string"},"shortFormMaxSeconds":{"type":"number"},"compareMax":{"type":"integer"},"notReported":{"type":"string"},"points":{"type":"array","items":{"type":"object","description":"One video on one network.","properties":{"id":{"type":"string","description":"`postId:platform`; pass it to compare."},"postId":{"type":"string"},"platform":{"type":"string"},"networkLabel":{"type":"string"},"publishedAt":{"type":"number"},"caption":{"type":"string"},"durationSeconds":{"type":"number","nullable":true,"description":"Video length in seconds; null = not reported."},"format":{"type":"string","enum":["short","long","unknown"],"description":"From a `format:` label, else length against the short-form cut-off (config)."},"hook":{"type":"string","nullable":true,"description":"`hook:` label value."},"hookTemplate":{"type":"string","nullable":true,"description":"`hook-template:` label value (Hook Studio)."},"campaignId":{"type":"string","nullable":true},"metrics":{"type":"object","description":"watchThroughPct, engagementRate, hookRetention and endRetention are percents (0-100); avgWatchTimeMs is milliseconds.","properties":{"watchThroughPct":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reach":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"avgWatchTimeMs":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"engagementRate":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"views":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"hookRetention":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"endRetention":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."}}},"retentionSupported":{"type":"boolean"},"hasRetention":{"type":"boolean"},"settling":{"type":"boolean","description":"Numbers may still change."},"videoUrl":{"type":"string","nullable":true},"thumbnailUrl":{"type":"string","nullable":true},"postUrl":{"type":"string","nullable":true,"description":"The live post on the network."},"url":{"type":"string","description":"The post page in flayr (API v2 only)."}}}},"period":{"type":"object","properties":{"days":{"type":"integer"},"sections":{"type":"object","properties":{"all":{"type":"object","properties":{"current":{"type":"object","properties":{"count":{"type":"integer"},"metrics":{"type":"object","properties":{"watchThroughPct":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"reach":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"avgWatchTimeMs":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"engagementRate":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"views":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"hookRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"endRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}}}}}},"previous":{"type":"object","properties":{"count":{"type":"integer"},"metrics":{"type":"object","properties":{"watchThroughPct":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"reach":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"avgWatchTimeMs":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"engagementRate":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"views":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"hookRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"endRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}}}}}}}},"short":{"type":"object","properties":{"current":{"type":"object","properties":{"count":{"type":"integer"},"metrics":{"type":"object","properties":{"watchThroughPct":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"reach":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"avgWatchTimeMs":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"engagementRate":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"views":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"hookRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"endRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}}}}}},"previous":{"type":"object","properties":{"count":{"type":"integer"},"metrics":{"type":"object","properties":{"watchThroughPct":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"reach":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"avgWatchTimeMs":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"engagementRate":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"views":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"hookRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"endRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}}}}}}}},"long":{"type":"object","properties":{"current":{"type":"object","properties":{"count":{"type":"integer"},"metrics":{"type":"object","properties":{"watchThroughPct":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"reach":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"avgWatchTimeMs":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"engagementRate":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"views":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"hookRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"endRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}}}}}},"previous":{"type":"object","properties":{"count":{"type":"integer"},"metrics":{"type":"object","properties":{"watchThroughPct":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"reach":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"avgWatchTimeMs":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"engagementRate":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"views":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"hookRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"endRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}}}}}}}},"unknown":{"type":"object","properties":{"current":{"type":"object","properties":{"count":{"type":"integer"},"metrics":{"type":"object","properties":{"watchThroughPct":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"reach":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"avgWatchTimeMs":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"engagementRate":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"views":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"hookRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"endRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}}}}}},"previous":{"type":"object","properties":{"count":{"type":"integer"},"metrics":{"type":"object","properties":{"watchThroughPct":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"reach":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"avgWatchTimeMs":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"engagementRate":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"views":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"hookRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}},"endRetention":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer","description":"How many videos reported it."}}}}}}}}}}}}},"hooks":{"type":"object","properties":{"hookSeconds":{"type":"number"},"groups":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["hook","hook-template","none"]},"value":{"type":"string","nullable":true},"label":{"type":"string"},"count":{"type":"integer"},"hookRetention":{"type":"object","properties":{"avg":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer"}}},"endRetention":{"type":"object","properties":{"avg":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer"}}},"watchThroughPct":{"type":"object","properties":{"avg":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reported":{"type":"integer"}}},"enoughData":{"type":"boolean","description":"At least the configured number of videos reported it; only these can lead."},"examples":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"platform":{"type":"string"},"caption":{"type":"string"},"videoUrl":{"type":"string","nullable":true},"thumbnailUrl":{"type":"string","nullable":true}}}},"pointIds":{"type":"array","items":{"type":"string"}}}}},"bestAtHook":{"type":"string","nullable":true},"bestToEnd":{"type":"string","nullable":true}}},"networks":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer"}}}},"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer"}}}},"truncated":{"type":"boolean","description":"More videos than the configured cap: the oldest were left out."},"generatedAt":{"type":"number"}}}}}},"400":{"description":"Bad `days`"},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan has no analytics"},"403":{"description":"The key lacks the read scope, or is bound to another brand"},"429":{"description":"Rate limited"}}}},"/api/v2/analytics/videos/compare":{"get":{"tags":["API v2"],"summary":"Overlay the retention curves of two or more videos","description":"Retention curves for point ids from the explorer, each in share-of-video and seconds units so videos of different lengths overlay; `axis` is the unit every curve fits. Videos with no curve, or out of scope, are listed in `missing`. Needs the read scope and Pro+.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ids","in":"query","required":true,"description":"Comma-separated point ids (`postId:platform`), 1 to 8.","schema":{"type":"string"}}],"responses":{"200":{"description":"Curves","content":{"application/json":{"schema":{"type":"object","properties":{"curves":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"postId":{"type":"string"},"platform":{"type":"string"},"networkLabel":{"type":"string"},"caption":{"type":"string"},"durationSeconds":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"basis":{"type":"string","enum":["seconds","ratio"]},"points":{"type":"array","items":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number","description":"Share of starting viewers still watching (0-1)."}}}},"share":{"type":"array","items":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number","description":"Share of starting viewers still watching (0-1)."}}},"nullable":true},"seconds":{"type":"array","items":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number","description":"Share of starting viewers still watching (0-1)."}}},"nullable":true},"hookRetention":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."}}}},"axis":{"type":"string","enum":["share","seconds"],"nullable":true},"missing":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reason":{"type":"string","enum":["not_found","no_curve"]}}}},"hookSeconds":{"type":"number"},"compareMax":{"type":"integer"}}}}}},"400":{"description":"Missing, malformed or too many ids"},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan has no analytics"},"403":{"description":"The key lacks the read scope, or is bound to another brand"},"429":{"description":"Rate limited"}}}},"/api/v2/posts/{id}/siblings":{"get":{"tags":["API v2"],"summary":"A post's siblings: the same video elsewhere and other variants","description":"The same video posted again (other networks or days) and other variants of the same piece (`variant-of:`, `experiment:`, `ab:` and `hook-template:` labels), each with its per-network video numbers (null = not reported). Needs the read scope and Pro+.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Post id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Siblings","content":{"application/json":{"schema":{"type":"object","properties":{"postId":{"type":"string"},"siblings":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"reason":{"type":"string","enum":["same_video","variant_of","experiment","ab","hook_template"]},"shared":{"type":"string","nullable":true},"caption":{"type":"string"},"publishedAt":{"type":"number","nullable":true},"status":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"points":{"type":"array","items":{"type":"object","description":"One video on one network.","properties":{"id":{"type":"string","description":"`postId:platform`; pass it to compare."},"postId":{"type":"string"},"platform":{"type":"string"},"networkLabel":{"type":"string"},"publishedAt":{"type":"number"},"caption":{"type":"string"},"durationSeconds":{"type":"number","nullable":true,"description":"Video length in seconds; null = not reported."},"format":{"type":"string","enum":["short","long","unknown"],"description":"From a `format:` label, else length against the short-form cut-off (config)."},"hook":{"type":"string","nullable":true,"description":"`hook:` label value."},"hookTemplate":{"type":"string","nullable":true,"description":"`hook-template:` label value (Hook Studio)."},"campaignId":{"type":"string","nullable":true},"metrics":{"type":"object","description":"watchThroughPct, engagementRate, hookRetention and endRetention are percents (0-100); avgWatchTimeMs is milliseconds.","properties":{"watchThroughPct":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"reach":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"avgWatchTimeMs":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"engagementRate":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"views":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"hookRetention":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."},"endRetention":{"type":"number","nullable":true,"description":"null = not reported by the network (or not yet)."}}},"retentionSupported":{"type":"boolean"},"hasRetention":{"type":"boolean"},"settling":{"type":"boolean","description":"Numbers may still change."},"videoUrl":{"type":"string","nullable":true},"thumbnailUrl":{"type":"string","nullable":true},"postUrl":{"type":"string","nullable":true,"description":"The live post on the network."},"url":{"type":"string","description":"The post page in flayr (API v2 only)."}}}},"url":{"type":"string"}}}},"notReported":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan has no analytics"},"403":{"description":"The key lacks the read scope, or is bound to another brand"},"404":{"description":"Not found (or another brand)"},"429":{"description":"Rate limited"}}}},"/api/v2/posts/{id}/memo":{"get":{"tags":["API v2"],"summary":"Read a post's \"when it posts\" memo","description":"The post's own memo, else its draft's (`level`). `livePath` is set once the post is live. Owner or brand member; a brand-bound key only reaches its own brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The post: `convexPostId` from POST /api/v2/publish."}],"responses":{"200":{"description":"{ id, memo: { id, level, notes, tasks[], notifiedAt } | null, livePath, canEdit }"},"401":{"description":"Unauthorized"},"404":{"description":"Not found or not visible to this key"}}},"put":{"tags":["API v2"],"summary":"Replace a post's \"when it posts\" memo","description":"Replaces the memo. A to-do that keeps its `id` (and text) keeps its tick. Before the post is live this edits its draft's memo when it has one (every booking of the draft copies it). Needs the `write`, `publish` or `admin` scope (a memo never touches a platform) and an editor role on the brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The post: `convexPostId` from POST /api/v2/publish."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"\"When it posts\" memo: the people-steps after the post goes live (reply to a comment, share to a personal account, pin a link, add a first comment flayr can't). Saved on the draft (else the post). When the post goes live, the brand's recipients (Brand → When a post goes live; default owners + admins) get ONE notice — in-app, email and push per their own settings — linking /publish/live/{convexPostId}: live links, the shared checklist, Copy buttons and a share link.","properties":{"notes":{"type":"string","maxLength":4000},"tasks":{"type":"array","maxItems":30,"items":{"oneOf":[{"type":"string","maxLength":500,"description":"The to-do, e.g. \"Share to personal LinkedIn\"."},{"type":"object","required":["text"],"properties":{"id":{"type":"string","description":"PUT only: keep an existing to-do (and its tick) by id."},"text":{"type":"string","maxLength":500},"copyText":{"type":"string","maxLength":5000,"description":"Text to paste (a reply, a first comment). The live page shows a Copy button."},"platform":{"type":"string","description":"The platform the step is for, e.g. \"youtube\"."},"url":{"type":"string","format":"uri","description":"Where to do it (http/https)."}}}]}}}}}}},"responses":{"200":{"description":"{ id, memoId, level: \"post\" | \"content\" }"},"401":{"description":"Unauthorized"},"403":{"description":"Missing scope, or no edit role on the brand"},"404":{"description":"Not found or not visible to this key"},"422":{"description":"Invalid memo (code memo_invalid)"}}}},"/api/v2/characters":{"get":{"tags":["API v2"],"summary":"List activated characters","description":"The ACTIVATED Character Studio characters this key can make scenes with. Characters are created and activated in the dashboard only; drafts and archived characters are not listed. Character Studio is a staged feature: a key whose owner does not have it gets 403. Character bible limits (characters; for lists, per item): `identity.name` 80, `identity.kind` 300, `identity.oneLiner` 3000, `identity.audience` 3000, `identity.toneWords` 60, `look.styleNotes` 3000, `look.description` 3000, `look.mustHave` 300, `look.neverDo` 300, `voice.gatewayModelId` 120, `voice.gatewayVoice` 80, `voice.instructions` 3000, `voice.voiceCloneId` 120, `voice.designed.description` 3000, `voice.designed.model` 120, `voice.designDraft.description` 300, `personality.traits` 300, `personality.humor` 3000, `personality.treatsAudience` 3000, `personality.catchphrases` 300, `personality.bannedPhrases` 300, `personality.boundaries` 3000, `personality.sampleLines` 300, `personality.exampleExchanges.user` 3000, `personality.exampleExchanges.character` 3000, `motion.cameraDefaults` 3000, `rig.poses` 40. Every scene uses the whole bible: image prompts carry all the style notes and must-haves; a clip prompt drops the palette, the never-dos and then the oldest style notes before it would ever cut the must-haves or your prompt.","x-character-bible-limits":{"type":"object","description":"Character bible limits, by bible field path. `text`: characters per value (per item for lists). `items`: list length. A bible over a limit is refused (the error names the field and the limit); nothing is cut.","properties":{"text":{"type":"object","additionalProperties":{"type":"integer"},"example":{"identity.name":80,"identity.kind":300,"identity.oneLiner":3000,"identity.audience":3000,"identity.toneWords":60,"look.styleNotes":3000,"look.description":3000,"look.mustHave":300,"look.neverDo":300,"voice.gatewayModelId":120,"voice.gatewayVoice":80,"voice.instructions":3000,"voice.voiceCloneId":120,"voice.designed.description":3000,"voice.designed.model":120,"voice.designDraft.description":300,"personality.traits":300,"personality.humor":3000,"personality.treatsAudience":3000,"personality.catchphrases":300,"personality.bannedPhrases":300,"personality.boundaries":3000,"personality.sampleLines":300,"personality.exampleExchanges.user":3000,"personality.exampleExchanges.character":3000,"motion.cameraDefaults":3000,"rig.poses":40}},"items":{"type":"object","additionalProperties":{"type":"integer"},"example":{"identity.toneWords":16,"look.palette":12,"look.mustHave":24,"look.neverDo":24,"look.canonicalAssetIds.turnaround":4,"look.canonicalAssetIds.expressions":6,"personality.traits":16,"personality.catchphrases":20,"personality.bannedPhrases":60,"personality.boundaries":20,"personality.sampleLines":20,"personality.exampleExchanges":10,"formats.seriesTemplateIds":20,"rig.poses":24}}},"x-limits":{"text":{"identity.name":80,"identity.kind":300,"identity.oneLiner":3000,"identity.audience":3000,"identity.toneWords":60,"look.styleNotes":3000,"look.description":3000,"look.mustHave":300,"look.neverDo":300,"voice.gatewayModelId":120,"voice.gatewayVoice":80,"voice.instructions":3000,"voice.voiceCloneId":120,"voice.designed.description":3000,"voice.designed.model":120,"voice.designDraft.description":300,"personality.traits":300,"personality.humor":3000,"personality.treatsAudience":3000,"personality.catchphrases":300,"personality.bannedPhrases":300,"personality.boundaries":3000,"personality.sampleLines":300,"personality.exampleExchanges.user":3000,"personality.exampleExchanges.character":3000,"motion.cameraDefaults":3000,"rig.poses":40},"items":{"identity.toneWords":16,"look.palette":12,"look.mustHave":24,"look.neverDo":24,"look.canonicalAssetIds.turnaround":4,"look.canonicalAssetIds.expressions":6,"personality.traits":16,"personality.catchphrases":20,"personality.bannedPhrases":60,"personality.boundaries":20,"personality.sampleLines":20,"personality.exampleExchanges":10,"formats.seriesTemplateIds":20,"rig.poses":24}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id from GET /api/v2/brands, or \"personal\". A brand-bound key lists its own brand (another brand → 403); omitted → the owner's active brand."}],"responses":{"200":{"description":"Characters","content":{"application/json":{"schema":{"type":"object","properties":{"characters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string","description":"Library label `character:<slug>` marks its scenes."},"kind":{"type":"string"},"status":{"type":"string","enum":["active"]},"brandId":{"type":"string","description":"The brand id, or \"personal\"."},"bibleVersionId":{"type":"string","nullable":true},"heroImageUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Invalid or missing API key"},"403":{"description":"Character Studio not enabled for the key owner, or a bound key named another brand"},"404":{"description":"Unknown brandId"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/bible":{"get":{"tags":["API v2"],"summary":"Read a character's draft bible","description":"The character's draft bible (what the dashboard wizard edits), with every field limit documented.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."}],"responses":{"200":{"description":"The draft bible","content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"],"description":"Read-only: activation happens in the dashboard."},"bible":{"type":"object","description":"A character bible. Every text field and list documents its limit; a PATCH over a limit is refused (422 CHARACTER_FIELD_TOO_LONG), never cut.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"identity":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"kind":{"type":"string","maxLength":300,"description":"e.g. \"glowing orange cartoon dragon\"."},"oneLiner":{"type":"string","maxLength":3000},"audience":{"type":"string","maxLength":3000},"toneWords":{"type":"array","maxItems":16,"items":{"type":"string","maxLength":60}},"originKind":{"type":"string","enum":["original","owned"]}}},"look":{"type":"object","properties":{"styleNotes":{"type":"string","maxLength":3000,"description":"Used whole in every image prompt."},"description":{"type":"string","maxLength":3000,"description":"The Look step's \"Describe it\"."},"palette":{"type":"array","maxItems":12,"items":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"mustHave":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":300},"description":"Never cut from any prompt."},"neverDo":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":300}},"canonicalAssetIds":{"type":"object","description":"Approved reference images of this character. Approving a Look image happens in the dashboard; only approved images of this character are accepted.","properties":{"hero":{"type":"string"},"turnaround":{"type":"array","maxItems":4,"items":{"type":"string"}},"expressions":{"type":"array","maxItems":6,"items":{"type":"string"}}}}}},"voice":{"type":"object","properties":{"source":{"type":"string","enum":["gateway","clone"]},"gatewayModelId":{"type":"string","maxLength":120},"gatewayVoice":{"type":"string","maxLength":80},"instructions":{"type":"string","maxLength":3000,"description":"How it should sound (stock voices that take style directions)."},"voiceCloneId":{"type":"string","maxLength":120,"description":"A flayr voice clone with recorded consent (checked on save)."},"exaggeration":{"type":"number","minimum":0.25,"maximum":2},"cfgWeight":{"type":"number","minimum":0,"maximum":1},"designed":{"type":"object","properties":{"description":{"type":"string","maxLength":3000},"model":{"type":"string","maxLength":120},"frozenAt":{"type":"number"}}},"pendingSource":{"type":"string","enum":["designed"],"description":"Wizard only: \"Design a new voice\" was picked but no designed voice is frozen yet. Never the voice that speaks."},"designDraft":{"type":"object","description":"Wizard only: the voice description typed but not designed yet.","properties":{"description":{"type":"string","maxLength":300}}}}},"personality":{"type":"object","properties":{"traits":{"type":"array","maxItems":16,"items":{"type":"string","maxLength":300}},"humor":{"type":"string","maxLength":3000},"treatsAudience":{"type":"string","maxLength":3000},"catchphrases":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300}},"bannedPhrases":{"type":"array","maxItems":60,"items":{"type":"string","maxLength":300}},"boundaries":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":3000}},"sampleLines":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300}},"exampleExchanges":{"type":"array","maxItems":10,"items":{"type":"object","properties":{"user":{"type":"string","maxLength":3000},"character":{"type":"string","maxLength":3000}}}}}},"motion":{"type":"object","properties":{"preset":{"type":"string","enum":["bouncy-cartoon","slow-epic","deadpan","hyper","calm"]},"cameraDefaults":{"type":"string","maxLength":3000}}},"formats":{"type":"object","properties":{"seriesTemplateIds":{"type":"array","maxItems":20,"items":{"type":"string"}}}}}},"ipCheck":{"type":"object","description":"PATCH with `check: true` only: the originality check result, as the dashboard stores it."}}}}}},"401":{"description":"Invalid or missing API key"},"403":{"description":"Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND (unknown, or another brand's character)"},"429":{"description":"Rate limited or monthly quota exceeded"}}},"patch":{"tags":["API v2"],"summary":"Edit a character's draft bible","description":"Merge a deep-partial patch into the DRAFT bible (objects merge, arrays and scalars replace, null removes an optional field), the same save the dashboard uses. The merged bible is validated before anything is written: a field over its limit is a 422 naming the field and the limit, and the text is never cut. `check: true` runs the originality check on the saved bible, like the dashboard. Activation, publishing a version and Look image approval stay in the dashboard; any other body key (e.g. `status`) is a 422 CHARACTER_DRAFT_ONLY. Body at most 256000 bytes. Requires the write (or admin) scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patch"],"additionalProperties":false,"properties":{"patch":{"type":"object","description":"A character bible. Every text field and list documents its limit; a PATCH over a limit is refused (422 CHARACTER_FIELD_TOO_LONG), never cut.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"identity":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"kind":{"type":"string","maxLength":300,"description":"e.g. \"glowing orange cartoon dragon\"."},"oneLiner":{"type":"string","maxLength":3000},"audience":{"type":"string","maxLength":3000},"toneWords":{"type":"array","maxItems":16,"items":{"type":"string","maxLength":60}},"originKind":{"type":"string","enum":["original","owned"]}}},"look":{"type":"object","properties":{"styleNotes":{"type":"string","maxLength":3000,"description":"Used whole in every image prompt."},"description":{"type":"string","maxLength":3000,"description":"The Look step's \"Describe it\"."},"palette":{"type":"array","maxItems":12,"items":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"mustHave":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":300},"description":"Never cut from any prompt."},"neverDo":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":300}},"canonicalAssetIds":{"type":"object","description":"Approved reference images of this character. Approving a Look image happens in the dashboard; only approved images of this character are accepted.","properties":{"hero":{"type":"string"},"turnaround":{"type":"array","maxItems":4,"items":{"type":"string"}},"expressions":{"type":"array","maxItems":6,"items":{"type":"string"}}}}}},"voice":{"type":"object","properties":{"source":{"type":"string","enum":["gateway","clone"]},"gatewayModelId":{"type":"string","maxLength":120},"gatewayVoice":{"type":"string","maxLength":80},"instructions":{"type":"string","maxLength":3000,"description":"How it should sound (stock voices that take style directions)."},"voiceCloneId":{"type":"string","maxLength":120,"description":"A flayr voice clone with recorded consent (checked on save)."},"exaggeration":{"type":"number","minimum":0.25,"maximum":2},"cfgWeight":{"type":"number","minimum":0,"maximum":1},"designed":{"type":"object","properties":{"description":{"type":"string","maxLength":3000},"model":{"type":"string","maxLength":120},"frozenAt":{"type":"number"}}},"pendingSource":{"type":"string","enum":["designed"],"description":"Wizard only: \"Design a new voice\" was picked but no designed voice is frozen yet. Never the voice that speaks."},"designDraft":{"type":"object","description":"Wizard only: the voice description typed but not designed yet.","properties":{"description":{"type":"string","maxLength":300}}}}},"personality":{"type":"object","properties":{"traits":{"type":"array","maxItems":16,"items":{"type":"string","maxLength":300}},"humor":{"type":"string","maxLength":3000},"treatsAudience":{"type":"string","maxLength":3000},"catchphrases":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300}},"bannedPhrases":{"type":"array","maxItems":60,"items":{"type":"string","maxLength":300}},"boundaries":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":3000}},"sampleLines":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300}},"exampleExchanges":{"type":"array","maxItems":10,"items":{"type":"object","properties":{"user":{"type":"string","maxLength":3000},"character":{"type":"string","maxLength":3000}}}}}},"motion":{"type":"object","properties":{"preset":{"type":"string","enum":["bouncy-cartoon","slow-epic","deadpan","hyper","calm"]},"cameraDefaults":{"type":"string","maxLength":3000}}},"formats":{"type":"object","properties":{"seriesTemplateIds":{"type":"array","maxItems":20,"items":{"type":"string"}}}}}},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."},"check":{"type":"boolean","default":false,"description":"Run the originality check on the saved bible (the result is returned as `ipCheck`)."}}}}}},"responses":{"200":{"description":"The draft bible","content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"],"description":"Read-only: activation happens in the dashboard."},"bible":{"type":"object","description":"A character bible. Every text field and list documents its limit; a PATCH over a limit is refused (422 CHARACTER_FIELD_TOO_LONG), never cut.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"identity":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"kind":{"type":"string","maxLength":300,"description":"e.g. \"glowing orange cartoon dragon\"."},"oneLiner":{"type":"string","maxLength":3000},"audience":{"type":"string","maxLength":3000},"toneWords":{"type":"array","maxItems":16,"items":{"type":"string","maxLength":60}},"originKind":{"type":"string","enum":["original","owned"]}}},"look":{"type":"object","properties":{"styleNotes":{"type":"string","maxLength":3000,"description":"Used whole in every image prompt."},"description":{"type":"string","maxLength":3000,"description":"The Look step's \"Describe it\"."},"palette":{"type":"array","maxItems":12,"items":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"mustHave":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":300},"description":"Never cut from any prompt."},"neverDo":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":300}},"canonicalAssetIds":{"type":"object","description":"Approved reference images of this character. Approving a Look image happens in the dashboard; only approved images of this character are accepted.","properties":{"hero":{"type":"string"},"turnaround":{"type":"array","maxItems":4,"items":{"type":"string"}},"expressions":{"type":"array","maxItems":6,"items":{"type":"string"}}}}}},"voice":{"type":"object","properties":{"source":{"type":"string","enum":["gateway","clone"]},"gatewayModelId":{"type":"string","maxLength":120},"gatewayVoice":{"type":"string","maxLength":80},"instructions":{"type":"string","maxLength":3000,"description":"How it should sound (stock voices that take style directions)."},"voiceCloneId":{"type":"string","maxLength":120,"description":"A flayr voice clone with recorded consent (checked on save)."},"exaggeration":{"type":"number","minimum":0.25,"maximum":2},"cfgWeight":{"type":"number","minimum":0,"maximum":1},"designed":{"type":"object","properties":{"description":{"type":"string","maxLength":3000},"model":{"type":"string","maxLength":120},"frozenAt":{"type":"number"}}},"pendingSource":{"type":"string","enum":["designed"],"description":"Wizard only: \"Design a new voice\" was picked but no designed voice is frozen yet. Never the voice that speaks."},"designDraft":{"type":"object","description":"Wizard only: the voice description typed but not designed yet.","properties":{"description":{"type":"string","maxLength":300}}}}},"personality":{"type":"object","properties":{"traits":{"type":"array","maxItems":16,"items":{"type":"string","maxLength":300}},"humor":{"type":"string","maxLength":3000},"treatsAudience":{"type":"string","maxLength":3000},"catchphrases":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300}},"bannedPhrases":{"type":"array","maxItems":60,"items":{"type":"string","maxLength":300}},"boundaries":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":3000}},"sampleLines":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":300}},"exampleExchanges":{"type":"array","maxItems":10,"items":{"type":"object","properties":{"user":{"type":"string","maxLength":3000},"character":{"type":"string","maxLength":3000}}}}}},"motion":{"type":"object","properties":{"preset":{"type":"string","enum":["bouncy-cartoon","slow-epic","deadpan","hyper","calm"]},"cameraDefaults":{"type":"string","maxLength":3000}}},"formats":{"type":"object","properties":{"seriesTemplateIds":{"type":"array","maxItems":20,"items":{"type":"string"}}}}}},"ipCheck":{"type":"object","description":"PATCH with `check: true` only: the originality check result, as the dashboard stores it."}}}}}},"400":{"description":"Invalid JSON, or a body over the size limit"},"401":{"description":"Invalid or missing API key"},"402":{"description":"Below the plan"},"403":{"description":"write scope missing, CHARACTER_EDIT_REQUIRED, Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND (unknown, or another brand's character)"},"409":{"description":"CHARACTER_ARCHIVED, VOICE_CONSENT_REQUIRED or VOICE_CONSENT_REVOKED"},"422":{"description":"A field over its limit: `{ error, code: \"CHARACTER_FIELD_TOO_LONG\", field: \"look.styleNotes\", limit: 3000 }`; another invalid bible value (CHARACTER_BIBLE_INVALID); a dashboard-only body key (CHARACTER_DRAFT_ONLY). Nothing is written or cut.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["CHARACTER_FIELD_TOO_LONG","CHARACTER_BIBLE_INVALID","CHARACTER_DRAFT_ONLY","invalid_request"]},"field":{"type":"string","description":"The dotted bible path (or body key) at fault."},"limit":{"type":"integer","description":"CHARACTER_FIELD_TOO_LONG only: the limit (characters, or items for a list)."}}}}}},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/rounds":{"get":{"tags":["API v2"],"summary":"List a character's Look rounds","description":"The Look iteration loop, oldest round first: the look each round was drawn from, its concepts and heroes with picks, reasons and notes, the round note, the version its feedback saved, and what changed since the round before.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."}}],"responses":{"200":{"description":"Rounds","content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"type":"string"},"status":{"type":"string"},"rounds":{"type":"array","items":{"type":"object","properties":{"round":{"type":"integer"},"startedAt":{"type":"string","format":"date-time"},"lookRecorded":{"type":"boolean"},"look":{"type":"object","nullable":true,"description":"The look the round was drawn from, frozen when the run started. null = made before rounds existed (\"look not recorded\").","properties":{"kind":{"type":"string"},"styleNotes":{"type":"string"},"description":{"type":"string"},"mustHave":{"type":"array","items":{"type":"string"}},"neverDo":{"type":"array","items":{"type":"string"}},"palette":{"type":"array","items":{"type":"string"}},"artAssetIds":{"type":"array","items":{"type":"string"}}}},"note":{"type":"string"},"appliedVersion":{"type":"integer","nullable":true,"description":"The bible version this round's feedback saved (\"Round N feedback\")."},"changesSincePrevious":{"type":"array","nullable":true,"items":{"type":"object","properties":{"field":{"type":"string","enum":["kind","description","styleNotes","mustHave","neverDo","palette","artAssetIds"]},"before":{},"after":{},"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}}}},"description":"null when either look was not recorded, or for the first round."},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"role":{"type":"string","enum":["concept","hero"]},"label":{"type":"string","description":"\"Run 2 · 3\" or \"Hero 4\"."},"url":{"type":"string","nullable":true},"blocked":{"type":"boolean"},"pick":{"type":"string","enum":["closest","keep","not"],"nullable":true},"reasons":{"type":"array","items":{"type":"string","enum":["face","proportions","style","outfit","colors","accessories","pose","background","on-model","off-model"]}},"note":{"type":"string"},"regions":{"type":"array","maxItems":8,"items":{"type":"object","required":["id","shape","x","y","w","h"],"properties":{"id":{"type":"string","maxLength":40,"description":"Your id for the region (letters, digits, - and _), unique on the image."},"shape":{"type":"string","enum":["box","lasso"]},"x":{"type":"number","minimum":0,"maximum":1,"description":"The bounding box, normalized to the image (0..1)."},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1},"points":{"type":"array","items":{"type":"number"},"maxItems":96,"description":"Lasso only: the outline as flat normalized pairs [x0, y0, x1, y1, …], 3 or more points."},"note":{"type":"string","maxLength":1000,"description":"What about this part, e.g. \"keep these brows\"."}}}}}}},"attachments":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"url":{"type":"string","nullable":true},"ipStatus":{"type":"string","description":"The originality check: pass, flag, block, checking, error or unchecked."},"blocked":{"type":"boolean"},"source":{"type":"string","enum":["paste","upload","frame"]},"note":{"type":"string"},"useAsReference":{"type":"boolean","description":"true: it leads the next concepts run's art."},"onAssetId":{"type":"string","nullable":true,"description":"The round image it is about; null = about the round."},"fromSceneId":{"type":"string","nullable":true},"frameAt":{"type":"number","nullable":true,"description":"Seconds into the clip the frame was grabbed at."},"regions":{"type":"array","maxItems":8,"items":{"type":"object","required":["id","shape","x","y","w","h"],"properties":{"id":{"type":"string","maxLength":40,"description":"Your id for the region (letters, digits, - and _), unique on the image."},"shape":{"type":"string","enum":["box","lasso"]},"x":{"type":"number","minimum":0,"maximum":1,"description":"The bounding box, normalized to the image (0..1)."},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1},"points":{"type":"array","items":{"type":"number"},"maxItems":96,"description":"Lasso only: the outline as flat normalized pairs [x0, y0, x1, y1, …], 3 or more points."},"note":{"type":"string","maxLength":1000,"description":"What about this part, e.g. \"keep these brows\"."}}}},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}}},"401":{"description":"Invalid or missing API key"},"403":{"description":"Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/rounds/feedback":{"post":{"tags":["API v2"],"summary":"Save feedback on a Look round","description":"One image's pick, reasons and note, or the round note (send what changed; the dashboard autosaves the same way). One \"closest\" per round: picking it moves it. Over a limit is a 422 naming the field and the limit (CHARACTER_FIELD_TOO_LONG), never cut. Requires the write (or admin) scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["round"],"additionalProperties":false,"properties":{"round":{"type":"integer","minimum":1,"description":"A round number from GET …/rounds (Round N = the Nth concepts run)."},"note":{"type":"string","maxLength":3000},"image":{"type":"object","required":["assetId"],"properties":{"assetId":{"type":"string"},"pick":{"type":"string","enum":["closest","keep","not"],"nullable":true,"description":"null clears it."},"reasons":{"type":"array","maxItems":10,"items":{"type":"string","enum":["face","proportions","style","outfit","colors","accessories","pose","background","on-model","off-model"]}},"note":{"type":"string","maxLength":3000},"regions":{"type":"array","maxItems":8,"items":{"type":"object","required":["id","shape","x","y","w","h"],"properties":{"id":{"type":"string","maxLength":40,"description":"Your id for the region (letters, digits, - and _), unique on the image."},"shape":{"type":"string","enum":["box","lasso"]},"x":{"type":"number","minimum":0,"maximum":1,"description":"The bounding box, normalized to the image (0..1)."},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1},"points":{"type":"array","items":{"type":"number"},"maxItems":96,"description":"Lasso only: the outline as flat normalized pairs [x0, y0, x1, y1, …], 3 or more points."},"note":{"type":"string","maxLength":1000,"description":"What about this part, e.g. \"keep these brows\"."}}},"description":"The image's highlighted parts (the whole list; [] clears them)."}}},"attachments":{"type":"array","maxItems":8,"description":"New images: { storageId } from POST /api/v2/media/upload-url (each goes into the character's art with the originality check, then joins the round; a blocked image is a 422 CHARACTER_UPLOAD_BLOCKED). Or { assetId } to update one already attached.","items":{"type":"object","properties":{"storageId":{"type":"string"},"assetId":{"type":"string"},"note":{"type":"string","maxLength":3000},"useAsReference":{"type":"boolean"},"onAssetId":{"type":"string","description":"New images only: the round image it is about."},"regions":{"type":"array","maxItems":8,"items":{"type":"object","required":["id","shape","x","y","w","h"],"properties":{"id":{"type":"string","maxLength":40,"description":"Your id for the region (letters, digits, - and _), unique on the image."},"shape":{"type":"string","enum":["box","lasso"]},"x":{"type":"number","minimum":0,"maximum":1,"description":"The bounding box, normalized to the image (0..1)."},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1},"points":{"type":"array","items":{"type":"number"},"maxItems":96,"description":"Lasso only: the outline as flat normalized pairs [x0, y0, x1, y1, …], 3 or more points."},"note":{"type":"string","maxLength":1000,"description":"What about this part, e.g. \"keep these brows\"."}}}}}}},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."}}}}}},"responses":{"200":{"description":"Saved"},"400":{"description":"Invalid JSON, or a body over 64000 bytes"},"401":{"description":"Invalid or missing API key"},"402":{"description":"Below the plan"},"403":{"description":"write scope missing, CHARACTER_EDIT_REQUIRED, Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND (unknown, or another brand's character), CHARACTER_ROUND_NOT_FOUND"},"409":{"description":"CHARACTER_ARCHIVED"},"422":{"description":"CHARACTER_FIELD_TOO_LONG { field, limit }, invalid_request"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/rounds/next-round":{"post":{"tags":["API v2"],"summary":"Suggest look changes for the next round","description":"The AI drafts changes to styleNotes, mustHave, neverDo and palette from the round's feedback and notes and the current draft look. Returns the proposed diff only: nothing is written and no image is made. Free (0 Embers). Requires the write (or admin) scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["round"],"additionalProperties":false,"properties":{"round":{"type":"integer","minimum":1,"description":"A round number from GET …/rounds (Round N = the Nth concepts run)."},"artAssetIds":{"type":"array","maxItems":3,"items":{"type":"string"},"description":"Up to 3 art image ids: the character's uploads or reference art (from use-as-reference). Omitted = the saved pick, else the newest 3. [] = no art (description only). Saved as the character's pick."},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."}}}}}},"responses":{"200":{"description":"The proposed diff","content":{"application/json":{"schema":{"type":"object","properties":{"round":{"type":"integer"},"summary":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["kind","description","styleNotes","mustHave","neverDo","palette","artAssetIds"]},"before":{},"after":{},"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}}}}},"embersCharged":{"type":"integer","enum":[0]}}}}}},"400":{"description":"Invalid JSON, or a body over 64000 bytes"},"401":{"description":"Invalid or missing API key"},"402":{"description":"Below the plan"},"403":{"description":"write scope missing, CHARACTER_EDIT_REQUIRED, Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND (unknown, or another brand's character), CHARACTER_ROUND_NOT_FOUND"},"409":{"description":"CHARACTER_ARCHIVED"},"422":{"description":"CHARACTER_ROUND_NO_FEEDBACK (rate or note something first), CHARACTER_TEXT_BLOCKED"},"429":{"description":"Rate limited or monthly quota exceeded"},"502":{"description":"CHARACTER_ROUND_DRAFT_FAILED"}}}},"/api/v2/characters/{id}/rounds/apply":{"post":{"tags":["API v2"],"summary":"Accept look changes from a round","description":"Writes the accepted values into the draft bible and saves a bible version \"Round N feedback\". Send only the parts you accept (edited as you like). Never generates images: make the next round's concepts in the dashboard. Draft characters only (an active character would publish a version: 422 CHARACTER_DRAFT_ONLY). Requires the write (or admin) scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["round","values"],"additionalProperties":false,"properties":{"round":{"type":"integer","minimum":1,"description":"A round number from GET …/rounds (Round N = the Nth concepts run)."},"values":{"type":"object","additionalProperties":false,"properties":{"styleNotes":{"type":"string","maxLength":3000},"mustHave":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":300}},"neverDo":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":300}},"palette":{"type":"array","maxItems":12,"items":{"type":"string","pattern":"^#[0-9a-f]{6}$"}}}},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."}}}}}},"responses":{"200":{"description":"The new version","content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"type":"string"},"round":{"type":"integer"},"version":{"type":"integer"},"versionId":{"type":"string"},"look":{"type":"object"}}}}}},"400":{"description":"Invalid JSON, or a body over 64000 bytes"},"401":{"description":"Invalid or missing API key"},"402":{"description":"Below the plan"},"403":{"description":"write scope missing, CHARACTER_EDIT_REQUIRED, Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND (unknown, or another brand's character), CHARACTER_ROUND_NOT_FOUND"},"409":{"description":"CHARACTER_ARCHIVED"},"422":{"description":"CHARACTER_FIELD_TOO_LONG { field, limit }, CHARACTER_BIBLE_INVALID, CHARACTER_TEXT_BLOCKED, CHARACTER_DRAFT_ONLY"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/rounds/concepts":{"post":{"tags":["API v2"],"summary":"Make the next Look round's 4 concepts","description":"Four draft concepts from the picked art and the draft look: Round N+1. The same service as the dashboard's Look step: Embers pass-through, refunded on failure, every image gets the originality check, never a Library draft. The pick is saved on the character and frozen in the round. Requires the write (or admin) scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","maxLength":3000,"description":"Omitted = the one saved on the draft."},"artAssetIds":{"type":"array","maxItems":3,"items":{"type":"string"},"description":"Up to 3 art image ids: the character's uploads or reference art (from use-as-reference). Omitted = the saved pick, else the newest 3. [] = no art (description only). Saved as the character's pick."},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."}}}}}},"responses":{"200":{"description":"Per-image results","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"string","enum":["concepts"]},"results":{"type":"array","items":{"type":"object"}},"embersCharged":{"type":"integer"}}}}}},"401":{"description":"Invalid or missing API key"},"402":{"description":"Below the plan, or not enough Embers (concepts)"},"403":{"description":"write scope missing, CHARACTER_EDIT_REQUIRED, Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND"},"422":{"description":"CHARACTER_FIELD_TOO_LONG { field, limit }, CHARACTER_REF_INVALID (art that is not usable), CHARACTER_UPLOAD_BLOCKED, CHARACTER_TEXT_BLOCKED"},"429":{"description":"Rate limited (concepts: the image bucket) or monthly quota exceeded"}}}},"/api/v2/characters/{id}/rounds/use-as-reference":{"post":{"tags":["API v2"],"summary":"Use a generated image as reference art","description":"A generated concept, hero, view or expression (assetId) or a finished test still (sceneId) becomes reference art without re-uploading: role \"reference\", linked to the original. Its originality check is the original's, or is run now when there is none. Idempotent per original.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"assetId":{"type":"string"},"sceneId":{"type":"string"},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."}},"description":"Exactly one of assetId or sceneId."}}}},"responses":{"200":{"description":"The reference art","content":{"application/json":{"schema":{"type":"object","properties":{"assetId":{"type":"string"},"ipCheck":{"type":"object"},"existing":{"type":"boolean"}}}}}},"401":{"description":"Invalid or missing API key"},"402":{"description":"Below the plan, or not enough Embers (concepts)"},"403":{"description":"write scope missing, CHARACTER_EDIT_REQUIRED, Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND"},"422":{"description":"invalid_request"},"429":{"description":"Rate limited (concepts: the image bucket) or monthly quota exceeded"}}}},"/api/v2/characters/{id}/rounds/own-art-note":{"post":{"tags":["API v2"],"summary":"\"This is my own art\" on a look-alike flag","description":"For a character marked as the owner's own art: clears an AI look-alike flag about a generic archetype (no franchise character named) on one image to pass, and the character's own flag once no image is still flagged. Recorded in the audit log. A named franchise character still needs the normal note and staff review.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assetId"],"additionalProperties":false,"properties":{"assetId":{"type":"string"},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". The key's brand must own the character."}}}}}},"responses":{"200":{"description":"Cleared","content":{"application/json":{"schema":{"type":"object","properties":{"assetId":{"type":"string"},"ipCheck":{"type":"object"},"characterCleared":{"type":"boolean"}}}}}},"401":{"description":"Invalid or missing API key"},"402":{"description":"Below the plan, or not enough Embers (concepts)"},"403":{"description":"write scope missing, CHARACTER_EDIT_REQUIRED, Character Studio not enabled, or a bound key named another brand"},"404":{"description":"CHARACTER_NOT_FOUND"},"422":{"description":"invalid_request, or not eligible (not owned, not a generic AI flag)"},"429":{"description":"Rate limited (concepts: the image bucket) or monthly quota exceeded"}}}},"/api/v2/characters/{id}/scenes":{"post":{"tags":["API v2"],"summary":"Make a scene with a character","description":"Make a still (synchronous, 10-60 s), a silent start-frame clip, or a narrated clip (the character speaking) with an activated character. Same services as the dashboard, so the look, voice, model table, Embers and refunds are identical. Outputs are Library drafts labelled `character:<slug>`; nothing is posted. Wizard test scenes (`purpose: \"test\"`) and the draft bible (`useDraft`) are dashboard-only (422). Requires the write (or admin) scope and the Pro+ plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["kind","prompt"],"properties":{"kind":{"type":"string","enum":["still"]},"prompt":{"type":"string","minLength":1,"maxLength":2000},"quality":{"type":"string","enum":["draft","final"],"default":"final"},"aspectRatio":{"type":"string","enum":["1:1","9:16","16:9","4:5"],"default":"1:1"},"model":{"type":"string","maxLength":120,"description":"Optional. Characters have no model picker: any model other than the plan's character model is refused (422), never swapped. `byok:` ids are refused."},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."},"purpose":{"type":"string","enum":["manual","chat","series"],"default":"manual","description":"Wizard test scenes (\"test\") are dashboard-only."}}},{"type":"object","required":["kind","prompt"],"properties":{"kind":{"type":"string","enum":["clip"]},"prompt":{"type":"string","minLength":1,"maxLength":1000,"description":"The motion / action; the character's look and motion style are added on the server."},"seconds":{"type":"integer","enum":[4,6,8],"default":8},"aspectRatio":{"type":"string","enum":["9:16","16:9"],"default":"9:16"},"quality":{"type":"string","enum":["final","preview"],"default":"final"},"startAssetId":{"type":"string","maxLength":64,"description":"An approved image of this character (default: the approved hero)."},"freshStill":{"type":"boolean","description":"Make a fresh on-model still first and start from it. Not with startAssetId."},"model":{"type":"string","maxLength":120,"description":"Optional. Characters have no model picker: any model other than the plan's character model is refused (422), never swapped. `byok:` ids are refused."},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."},"purpose":{"type":"string","enum":["manual","chat","series"],"default":"manual","description":"Wizard test scenes (\"test\") are dashboard-only."}}},{"type":"object","required":["kind","script"],"properties":{"kind":{"type":"string","enum":["narrated"]},"script":{"type":"string","minLength":1,"maxLength":600,"description":"What the character says."},"shots":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["prompt","seconds"],"properties":{"prompt":{"type":"string","maxLength":500},"seconds":{"type":"integer","enum":[4,6,8]}}},"description":"Default: one shot per beat of the script."},"action":{"type":"string","maxLength":500,"description":"One \"what happens\" for every default shot."},"aspectRatio":{"type":"string","enum":["9:16","16:9"],"default":"9:16"},"quality":{"type":"string","enum":["final","preview"],"default":"final"},"captions":{"type":"boolean","default":true},"startAssetId":{"type":"string","maxLength":64},"voiceMatch":{"type":"integer","minimum":1,"maximum":4,"description":"How closely the mouth and the voice line up, and what it costs in Embers. 1 Voice-over only: The character’s voice over the clip. The mouth isn’t matched to the words. 2 Base: The voice is moved as a whole to line up with the mouth. 3 Better: The mouth moves to the character’s own voice. The voice plays as recorded. 4 Best: Better, made twice. You get the take with the closest sync, with its score. Omitted: the default stop. A stop that is not available yet, or that needs a clip model with its own speech (3 and 4, Veo 3), is refused with 422 VOICE_MATCH_NOT_ENABLED or VOICE_MATCH_NEEDS_NATIVE_AUDIO_MODEL before anything is charged. The character's own voice is always the one delivered."},"model":{"type":"string","maxLength":120,"description":"Optional. Characters have no model picker: any model other than the plan's character model is refused (422), never swapped. `byok:` ids are refused."},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."},"purpose":{"type":"string","enum":["manual","series"],"default":"manual"}}},{"type":"object","required":["kind","retrySceneId"],"properties":{"kind":{"type":"string","enum":["narrated"]},"retrySceneId":{"type":"string","maxLength":64,"description":"Re-run only the failed stage of this narrated scene."}}}]}}}},"responses":{"200":{"description":"Still made","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"The scene id; poll GET /api/v2/generate/status/{jobId} (source \"character\")."},"sceneId":{"type":"string"},"kind":{"type":"string","enum":["still","clip","narrated"]},"status":{"type":"string","enum":["completed","pending"]},"characterId":{"type":"string"},"model":{"type":"string"},"bibleVersionId":{"type":"string"},"imageUrl":{"type":"string","description":"still only."},"contentId":{"type":"string","description":"still only: the Library draft."},"embersCharged":{"type":"integer","description":"still only."},"embers":{"type":"integer","description":"clip / narrated: Embers charged (refunded on failure)."},"generationJobId":{"type":"string","description":"clip only."},"startAssetId":{"type":"string","description":"clip only."},"voiceMatch":{"type":"integer","minimum":1,"maximum":4,"description":"narrated only: the voice match stop it runs at."}}}}}},"202":{"description":"Clip or narrated scene queued","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"The scene id; poll GET /api/v2/generate/status/{jobId} (source \"character\")."},"sceneId":{"type":"string"},"kind":{"type":"string","enum":["still","clip","narrated"]},"status":{"type":"string","enum":["completed","pending"]},"characterId":{"type":"string"},"model":{"type":"string"},"bibleVersionId":{"type":"string"},"imageUrl":{"type":"string","description":"still only."},"contentId":{"type":"string","description":"still only: the Library draft."},"embersCharged":{"type":"integer","description":"still only."},"embers":{"type":"integer","description":"clip / narrated: Embers charged (refunded on failure)."},"generationJobId":{"type":"string","description":"clip only."},"startAssetId":{"type":"string","description":"clip only."},"voiceMatch":{"type":"integer","minimum":1,"maximum":4,"description":"narrated only: the voice match stop it runs at."}}}}}},"400":{"description":"Invalid JSON body"},"401":{"description":"Invalid or missing API key"},"402":{"description":"Below the plan, not enough Embers, or CHARACTER_SCENE_NOT_IN_PLAN"},"403":{"description":"write scope missing, Character Studio not enabled, a bound key naming another brand, or CHARACTER_EDIT_REQUIRED"},"404":{"description":"CHARACTER_NOT_FOUND"},"409":{"description":"CHARACTER_NOT_ACTIVE (a draft or archived character)"},"422":{"description":"Validation, CHARACTER_SCENE_KIND_UNSUPPORTED, CHARACTER_MODEL_UNSUPPORTED, CHARACTER_BYOK_UNSUPPORTED, CHARACTER_CLIP_NEEDS_START_FRAME, CHARACTER_IP_BLOCKED, VOICE_MATCH_NOT_ENABLED, VOICE_MATCH_NEEDS_NATIVE_AUDIO_MODEL, …"},"429":{"description":"Rate limited (image bucket for stills, video for clips) or monthly quota exceeded"}}}},"/api/v2/characters/{id}/motion":{"get":{"tags":["API v2"],"summary":"List a character's motion library","description":"The character's silent motion clips, newest first, and the latest library batch (or `batchId`) with each item's state: poll it after POST …/motion/batch. Needs the read (or admin) scope. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional guard: the character's brand id, or \"personal\"."},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["idle","talk","gesture","reaction","enter","exit","transition","signature"]}},{"name":"aspect","in":"query","required":false,"schema":{"type":"string","enum":["16:9","9:16"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","approved","retired"]}},{"name":"batchId","in":"query","required":false,"schema":{"type":"string"},"description":"A batch id from POST …/motion/batch or …/rounds regenerate."}],"responses":{"200":{"description":"Clips and the batch","content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"type":"string"},"clips":{"type":"array","items":{"type":"object","properties":{"clipId":{"type":"string"},"catalogKey":{"type":"string"},"category":{"type":"string","enum":["idle","talk","gesture","reaction","enter","exit","transition","signature"]},"tags":{"type":"array","items":{"type":"string"}},"energy":{"type":"string","enum":["low","mid","high"]},"speaking":{"type":"boolean"},"mouth":{"type":"string"},"aspect":{"type":"string","enum":["16:9","9:16"]},"seconds":{"type":"number"},"loop":{"type":"string","enum":["none","seamless","pingpong","crossfade"]},"source":{"type":"string","enum":["veo","puppet","upload","shot_take"]},"model":{"type":"string"},"lookVersion":{"type":"integer"},"olderLook":{"type":"boolean","description":"Made from an older look than the active one."},"take":{"type":"integer"},"parentClipId":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","approved","retired"]},"ipStatus":{"type":"string","description":"The originality check; only \"pass\" clips are reused."},"onModel":{"type":"string","enum":["on-model","off-model","unknown"]},"embersCharged":{"type":"integer"},"usageCount":{"type":"integer"},"contentId":{"type":"string","nullable":true},"batchId":{"type":"string","nullable":true},"videoUrl":{"type":"string","nullable":true},"createdAt":{"type":"integer","description":"Epoch ms."}}}},"batch":{"type":"object","properties":{"batchId":{"type":"string"},"state":{"type":"string"},"embers":{"type":"integer"},"createdAt":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"catalogKey":{"type":"string"},"aspect":{"type":"string"},"seconds":{"type":"integer"},"state":{"type":"string"},"clipId":{"type":"string","nullable":true},"videoUrl":{"type":"string","nullable":true},"needsReview":{"type":"boolean"}}}}},"nullable":true}}},"example":{"characterId":"k57characterember","clips":[{"clipId":"k57clipnod00000001","catalogKey":"gesture.nod","category":"gesture","tags":["nod"],"energy":"low","speaking":false,"mouth":"closed","aspect":"9:16","seconds":4,"loop":"none","source":"veo","model":"google/veo-3.1-fast","lookVersion":3,"olderLook":false,"take":1,"parentClipId":null,"status":"approved","ipStatus":"pass","onModel":"on-model","embersCharged":120,"usageCount":2,"contentId":"k57content0000001","batchId":"k57batch000000001","videoUrl":"https://cdn.flayr.social/clip.mp4","createdAt":1760000000000}],"batch":null}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/motion/batch":{"post":{"tags":["API v2"],"summary":"Build the motion library (batch)","description":"Price, then start, a batch of silent clips. `items` default to the starter batch (+ `signatureKeys`). Items a build credit covers are Included (0 Embers). Each clip job is charged once and refunded once on failure; items run one at a time (load waits in the queue, no per-user caps). Needs the write (or admin) scope and the Pro+ plan. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"estimate","in":"query","required":false,"schema":{"type":"string","enum":["1","true"]},"description":"Price only: answers the estimate and never spends, even with `confirmEmbers`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"catalogKey":{"type":"string","description":"A motion catalog key, e.g. \"idle.breathe\"."},"aspect":{"type":"string","enum":["16:9","9:16"]},"seconds":{"type":"integer","enum":[4,6,8]}},"required":["catalogKey","aspect","seconds"]},"minItems":1,"maxItems":60},"signatureKeys":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":6},"confirmEmbers":{"type":"integer","description":"The estimate's total in Embers you approve (from `?estimate=1`). Absent = price only, nothing spent. A different total → 409 with the new estimate.","minimum":0},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."}}},"example":{"items":[{"catalogKey":"gesture.nod","aspect":"9:16","seconds":4}],"confirmEmbers":360}}}},"responses":{"200":{"description":"The estimate (`?estimate=1` or no confirmEmbers): nothing spent, no job","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["estimate"]},"estimate":{"type":"object","properties":{"embers":{"type":"integer","description":"The total in Embers."},"parts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"units":{"type":"number"},"embers":{"type":"integer"},"label":{"type":"string"}}}}},"additionalProperties":true},"items":{"type":"array","items":{"type":"object","properties":{"catalogKey":{"type":"string","description":"A motion catalog key, e.g. \"idle.breathe\"."},"aspect":{"type":"string","enum":["16:9","9:16"]},"seconds":{"type":"integer","enum":[4,6,8]}},"required":["catalogKey","aspect","seconds"]}},"model":{"type":"string"},"reframe":{"type":"array","items":{"type":"string"}},"notIncluded":{"type":"boolean"}}},"example":{"status":"estimate","estimate":{"embers":360,"parts":[{"kind":"clip","units":4,"embers":360,"label":"3 × 4 s clip"}]},"items":[{"catalogKey":"gesture.nod","aspect":"9:16","seconds":4}],"model":"google/veo-3.1-fast","reframe":[]}}}},"202":{"description":"Started","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["queued"]},"batchId":{"type":"string"},"estimate":{"type":"object","properties":{"embers":{"type":"integer","description":"The total in Embers."},"parts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"units":{"type":"number"},"embers":{"type":"integer"},"label":{"type":"string"}}}}},"additionalProperties":true}}},"example":{"status":"queued","batchId":"k57batch000000001","estimate":{"embers":360,"parts":[{"kind":"clip","units":4,"embers":360,"label":"3 × 4 s clip"}]}}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"402":{"description":"insufficient_credits: not enough Embers for the whole estimate (`required`, `remaining`); nothing charged"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"409":{"description":"MOTION_ESTIMATE_CHANGED / stale_estimate: `confirmEmbers` is not the current total (the new estimate is in the body; nothing started)"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/motion/{clipId}":{"get":{"tags":["API v2"],"summary":"One clip and its takes","description":"Every take of the clip's catalog key and aspect, oldest first, with videos, feedback, checks and \"older look\"; `pending` = a take is being made. Needs the read (or admin) scope. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"clipId","in":"path","required":true,"schema":{"type":"string"},"description":"A clip id from GET …/motion."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional guard: the character's brand id, or \"personal\"."}],"responses":{"200":{"description":"Takes","content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"type":"string"},"catalogKey":{"type":"string"},"aspect":{"type":"string"},"clipId":{"type":"string"},"activeLookVersion":{"type":"integer","nullable":true},"pending":{"type":"boolean"},"takes":{"type":"array","items":{"type":"object","properties":{"clipId":{"type":"string"},"take":{"type":"integer"},"status":{"type":"string"},"videoUrl":{"type":"string","nullable":true},"olderLook":{"type":"boolean"},"ipStatus":{"type":"string"},"feedback":{"type":"object"}},"additionalProperties":true}}}},"example":{"characterId":"k57characterember","catalogKey":"gesture.nod","aspect":"9:16","clipId":"k57clipnod00000001","activeLookVersion":3,"pending":false,"takes":[{"clipId":"k57clipnod00000001","take":1,"status":"draft","videoUrl":null,"olderLook":false,"ipStatus":"pass","feedback":{}}]}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}},"patch":{"tags":["API v2"],"summary":"Tag, approve or retire a clip","description":"Free. `tags` replace the clip's tags (trimmed, de-duplicated). `status: approved` lets the storyboard matcher reuse it (409 MOTION_CLIP_FLAGGED / MOTION_CLIP_UNCHECKED until its originality check passes); `retired` = never reused (nothing is deleted). Needs the write (or admin) scope and the Pro+ plan. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"clipId","in":"path","required":true,"schema":{"type":"string"},"description":"A clip id from GET …/motion."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"status":{"type":"string","enum":["approved","retired"]},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."}}},"example":{"tags":["nod","yes"],"status":"approved"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"clipId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string"}}},"example":{"clipId":"k57clipnod00000001","tags":["nod","yes"],"status":"approved"}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"409":{"description":"MOTION_CLIP_FLAGGED, MOTION_CLIP_UNCHECKED or MOTION_CLIP_NO_VIDEO"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/motion/{clipId}/rounds":{"post":{"tags":["API v2"],"summary":"Iterate a clip: feedback, next take, regenerate","description":"`feedback` autosaves on the take (each field given replaces the saved one; `pick: null` / `regions: []` clear); free. `nextTake` drafts the next take's action from that feedback (one text call, free, nothing written). `regenerate` prices, then (with `confirmEmbers`) makes, a new take at the clip price: charged once, refunded once; poll GET …/motion?batchId=. `prompt` is what the character does, not the model prompt. Needs the write (or admin) scope and the Pro+ plan. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"clipId","in":"path","required":true,"schema":{"type":"string"},"description":"A clip id from GET …/motion."},{"name":"estimate","in":"query","required":false,"schema":{"type":"string","enum":["1","true"]},"description":"Price only: answers the estimate and never spends, even with `confirmEmbers`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["feedback","nextTake","regenerate"]},"pick":{"type":"string","description":"feedback only.","enum":["closest","keep","not"],"nullable":true},"reasons":{"type":"array","items":{"type":"string","enum":["on-model","motion","timing","loop-seam","face","hands","props","background"]},"description":"feedback only."},"note":{"type":"string","description":"feedback only.","maxLength":3000},"regions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":40},"shape":{"type":"string","enum":["box","lasso"]},"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"},"points":{"type":"array","items":{"type":"number"}},"note":{"type":"string","maxLength":1000},"tag":{"type":"string","enum":["pro","con","remove"]}},"required":["id","shape","x","y","w","h","note"]},"maxItems":8,"description":"feedback only: highlighted parts of the grabbed frame (normalized 0..1)."},"frameAt":{"type":"number","minimum":0,"description":"feedback only: the second the regions were drawn on."},"prompt":{"type":"string","description":"regenerate only: the next take's action.","maxLength":1000},"confirmEmbers":{"type":"integer","description":"The estimate's total in Embers you approve (from `?estimate=1`). Absent = price only, nothing spent. A different total → 409 with the new estimate.","minimum":0},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."}},"required":["action"]},"example":{"action":"regenerate","prompt":"Ember nods twice, slower.","confirmEmbers":120}}}},"responses":{"200":{"description":"feedback → { clipId, ok }; nextTake → the drafted action; regenerate without confirmEmbers → the estimate (nothing spent)","content":{"application/json":{"schema":{"type":"object","properties":{"clipId":{"type":"string"},"ok":{"type":"boolean"},"take":{"type":"integer"},"before":{"type":"string"},"after":{"type":"string"},"summary":{"type":"string"},"embersCharged":{"type":"integer"},"status":{"type":"string"},"estimate":{"type":"object","properties":{"embers":{"type":"integer","description":"The total in Embers."},"parts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"units":{"type":"number"},"embers":{"type":"integer"},"label":{"type":"string"}}}}},"additionalProperties":true}},"additionalProperties":true},"example":{"status":"estimate","estimate":{"embers":360,"parts":[{"kind":"clip","units":4,"embers":360,"label":"3 × 4 s clip"}]},"take":2}}}},"202":{"description":"regenerate started","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["queued"]},"batchId":{"type":"string"},"take":{"type":"integer"},"estimate":{"type":"object","properties":{"embers":{"type":"integer","description":"The total in Embers."},"parts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"units":{"type":"number"},"embers":{"type":"integer"},"label":{"type":"string"}}}}},"additionalProperties":true}}},"example":{"status":"queued","batchId":"k57batch000000002","take":2,"estimate":{"embers":360,"parts":[{"kind":"clip","units":4,"embers":360,"label":"3 × 4 s clip"}]}}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"402":{"description":"insufficient_credits: not enough Embers for the whole estimate (`required`, `remaining`); nothing charged"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"409":{"description":"MOTION_ESTIMATE_CHANGED / stale_estimate: `confirmEmbers` is not the current total (the new estimate is in the body; nothing started)"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/motion/puppet":{"post":{"tags":["API v2"],"summary":"Make a silent 2D puppet clip","description":"A pose-only clip from a motion catalog key, drawn by the character's 2D rig on the hive render worker. No voice, no model cost: the render fee only, charged once and refunded once if the render fails. Also behind the characterPuppet toggle. Poll GET …/motion/puppet?jobId=. Needs the write (or admin) scope and the Pro+ plan. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"estimate","in":"query","required":false,"schema":{"type":"string","enum":["1","true"]},"description":"Price only: answers the estimate and never spends, even with `confirmEmbers`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"catalogKey":{"type":"string","maxLength":60},"seconds":{"type":"integer","minimum":1,"maximum":30},"format":{"type":"string","enum":["9:16","16:9"],"default":"9:16"},"confirmEmbers":{"type":"integer","description":"The estimate's total in Embers you approve (from `?estimate=1`). Absent = price only, nothing spent. A different total → 409 with the new estimate.","minimum":0},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."}},"required":["catalogKey","seconds"]},"example":{"catalogKey":"talk.calm.a","seconds":6,"format":"16:9","confirmEmbers":10}}}},"responses":{"200":{"description":"The estimate: nothing reserved, charged or queued","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["estimate"]},"estimate":{"type":"object","properties":{"render":{"type":"integer"}}},"catalogKey":{"type":"string"},"format":{"type":"string"},"seconds":{"type":"integer"}}},"example":{"status":"estimate","estimate":{"render":10},"catalogKey":"talk.calm.a","format":"16:9","seconds":6}}}},"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["queued"]},"jobId":{"type":"string"},"sceneId":{"type":"string"},"catalogKey":{"type":"string"},"format":{"type":"string"},"embers":{"type":"object","properties":{"render":{"type":"integer"}}}}},"example":{"status":"queued","jobId":"k57videojob000001","sceneId":"k57scene000000001","catalogKey":"talk.calm.a","format":"16:9","embers":{"render":10}}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"402":{"description":"insufficient_credits: not enough Embers for the whole estimate (`required`, `remaining`); nothing charged"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"409":{"description":"MOTION_ESTIMATE_CHANGED / stale_estimate: `confirmEmbers` is not the current total (the new estimate is in the body; nothing started)"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}},"get":{"tags":["API v2"],"summary":"A silent puppet render's status","description":"queued, running, done (with the video) or failed; a failed or stale render's fee is refunded once here. Needs the read (or admin) scope. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional guard: the character's brand id, or \"personal\"."},{"name":"jobId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"contentId":{"type":"string","nullable":true},"videoUrl":{"type":"string","nullable":true},"error":{"type":"string"},"refunded":{"type":"boolean"}}},"example":{"jobId":"k57videojob000001","status":"done","contentId":"k57content0000001","videoUrl":"https://cdn.flayr.social/puppet.mp4"}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/storyboards":{"get":{"tags":["API v2"],"summary":"List a character's storyboards","description":"Needs the read (or admin) scope. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional guard: the character's brand id, or \"personal\"."}],"responses":{"200":{"description":"Storyboards","content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"type":"string"},"storyboards":{"type":"array","items":{"type":"object","description":"A storyboard summary.","additionalProperties":true}}}},"example":{"characterId":"k57characterember","storyboards":[{"_id":"k57storyboardone01","title":"Launch"}]}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}},"post":{"tags":["API v2"],"summary":"Create a storyboard (brief → draft)","description":"Creates a storyboard. With `draft: true` and a brief, also drafts its shots from the brief (one text call, charged only when it succeeded; a 402 still creates the storyboard, without a draft, and names its `storyboardId`). Needs the write (or admin) scope and the Pro+ plan. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"brief":{"type":"string","maxLength":2000},"draft":{"type":"boolean"},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."}}},"example":{"title":"Launch","brief":"Ember announces the spring menu in 30 seconds.","draft":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"storyboardId":{"type":"string"},"revision":{"type":"integer"},"draft":{"type":"object","description":"The drafted shots.","additionalProperties":true},"embersCharged":{"type":"integer"}}},"example":{"storyboardId":"k57storyboardone01","revision":2,"draft":{"shots":[]},"embersCharged":1}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"402":{"description":"insufficient_credits: not enough Embers for the whole estimate (`required`, `remaining`); nothing charged"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/storyboards/{sid}":{"get":{"tags":["API v2"],"summary":"One storyboard and its revisions","description":"Needs the read (or admin) scope. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"A storyboard id from GET …/storyboards."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional guard: the character's brand id, or \"personal\"."}],"responses":{"200":{"description":"The storyboard","content":{"application/json":{"schema":{"type":"object","properties":{"storyboard":{"type":"object","description":"Shots, keyframes, pins, voice, style.","additionalProperties":true},"revisions":{"type":"array","items":{"type":"object","description":"A revision.","additionalProperties":true}}}},"example":{"storyboard":{"_id":"k57storyboardone01","title":"Launch","shots":[]},"revisions":[{"n":1}]}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}},"patch":{"tags":["API v2"],"summary":"Edit a storyboard: fields, shots, keyframes, pins","description":"Every edit is a revision, applied in order (fields, shots, keyframes, pins); a refusal stops there and answers its error with `applied`. Never spends: keyframes are an existing image, an upload or a grabbed frame, each through the same fail-closed originality check as the dashboard (paid by flayr). A pin keeps a library clip on a shot for the plan (`clipId: null` unpins). Needs the write (or admin) scope and the Pro+ plan. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"A storyboard id from GET …/storyboards."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"brief":{"type":"string","maxLength":2000},"script":{"type":"string","maxLength":6000},"style":{"type":"string","enum":["veo","puppet","mixed"]},"alsoShort":{"type":"boolean","description":"Also render the 9:16 short."},"voice":{"type":"object","properties":{"source":{"type":"string","enum":["character","clone","designed"]},"voiceId":{"type":"string","maxLength":120}},"required":["source"]},"voiceMatch":{"type":"integer","minimum":1,"maximum":4},"shots":{"type":"array","items":{"type":"object","properties":{"shotId":{"type":"string"},"beat":{"type":"string","maxLength":300},"intent":{"type":"string","maxLength":200,"nullable":true},"note":{"type":"string","maxLength":500},"line":{"type":"string","maxLength":400,"nullable":true},"speaker":{"type":"string","enum":["character","user","none"]},"camera":{"type":"string","maxLength":120},"seconds":{"type":"integer","enum":[4,6,8]},"motion":{"type":"object","properties":{"kind":{"type":"string","enum":["library","puppet","generate"]},"clipId":{"type":"string"}}},"voiceMatch":{"type":"integer","minimum":1,"maximum":4,"nullable":true},"clearKeyframe":{"type":"boolean"},"needsEndFrame":{"type":"boolean"},"clearEndKeyframe":{"type":"boolean"}},"required":["shotId"]},"minItems":1,"maxItems":40},"keyframes":{"type":"array","items":{"type":"object","properties":{"shotId":{"type":"string"},"kind":{"type":"string","description":"asset = one of the character's images; upload = a storageId from POST /api/v2/media/upload-url; frame = a grabbed frame (upload) with its lineage. Generated keyframes spend and stay in the dashboard.","enum":["asset","upload","frame"]},"slot":{"type":"string","enum":["start","end"]},"assetId":{"type":"string"},"storageId":{"type":"string"},"fromClipId":{"type":"string"},"fromTakeContentId":{"type":"string"},"frameAt":{"type":"number","minimum":0}},"required":["shotId","kind"]},"minItems":1,"maxItems":40},"pins":{"type":"array","items":{"type":"object","properties":{"shotId":{"type":"string"},"clipId":{"type":"string","nullable":true}},"required":["shotId","clipId"]},"minItems":1,"maxItems":40},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."}}},"example":{"title":"Launch v2","shots":[{"shotId":"shot_1","line":"Spring is here!","seconds":6}],"pins":[{"shotId":"shot_1","clipId":"k57clipnod00000001"}]}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","nullable":true},"storyboard":{"type":"object","description":"The storyboard after the edits.","additionalProperties":true}}},"example":{"revision":7,"storyboard":{"_id":"k57storyboardone01","title":"Launch v2"}}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"409":{"description":"SHOT_LIMIT / IN_PROGRESS"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/storyboards/{sid}/plan":{"post":{"tags":["API v2"],"summary":"Plan reuse for a storyboard","description":"Per shot, the library clip it reuses (and why, with the fit ops) or that it is generated, the totals and what regenerating everything would cost; saved as the storyboard's last plan. Free: nothing is made or charged. Priced at the key's plan. Needs the write (or admin) scope and the Pro+ plan. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"A storyboard id from GET …/storyboards."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"aspect":{"type":"string","enum":["16:9","9:16"],"default":"16:9"},"seed":{"type":"integer","description":"Tie-break seed; absent = stable per storyboard.","minimum":0},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."}}},"example":{"aspect":"16:9"}}}},"responses":{"200":{"description":"The plan","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","description":"shots[], total, regenerateAllTotal, aspect, seed, tier.","additionalProperties":true}}},"example":{"plan":{"total":40,"regenerateAllTotal":900,"aspect":"16:9","shots":[]}}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/storyboards/{sid}/assemble":{"post":{"tags":["API v2"],"summary":"Assemble a storyboard into a video","description":"Voice first, shots sized from the real lines, only the gaps generated, one render per output (16:9 master, optional 9:16 short). Each part is charged once and refunded once. Poll GET …/{sid}/status. Needs the write (or admin) scope and the Pro+ plan. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"A storyboard id from GET …/storyboards."},{"name":"estimate","in":"query","required":false,"schema":{"type":"string","enum":["1","true"]},"description":"Price only: answers the estimate and never spends, even with `confirmEmbers`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmEmbers":{"type":"integer","description":"The estimate's total in Embers you approve (from `?estimate=1`). Absent = price only, nothing spent. A different total → 409 with the new estimate.","minimum":0},"brandId":{"type":"string","description":"Optional guard: the character's brand id, or \"personal\". A brand-bound key only reaches its own brand."}}},"example":{"confirmEmbers":300}}}},"responses":{"200":{"description":"The estimate (`?estimate=1` or no confirmEmbers; nothing spent), or { unchanged: true, embers: 0, contentId } when nothing changed","content":{"application/json":{"schema":{"type":"object","properties":{"estimate":{"type":"object","properties":{"embers":{"type":"integer","description":"The total in Embers."},"parts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"units":{"type":"number"},"embers":{"type":"integer"},"label":{"type":"string"}}}}},"additionalProperties":true},"unchanged":{"type":"boolean"},"missingKeyframes":{"type":"array","items":{"type":"string"}},"outputs":{"type":"array","items":{"type":"string"}},"lastContentId":{"type":"string","nullable":true},"voice":{"type":"object","properties":{"label":{"type":"string"}}},"tier":{"type":"string"}},"additionalProperties":true},"example":{"estimate":{"embers":360,"parts":[{"kind":"clip","units":4,"embers":360,"label":"3 × 4 s clip"}]},"unchanged":false,"missingKeyframes":[],"outputs":["16:9"],"lastContentId":null,"voice":{"label":"Ember"},"tier":"pro"}}}},"202":{"description":"Started","content":{"application/json":{"schema":{"type":"object","properties":{"assemblyId":{"type":"string"},"embers":{"type":"integer"}}},"example":{"assemblyId":"k57assembly000001","embers":300}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"402":{"description":"insufficient_credits: not enough Embers for the whole estimate (`required`, `remaining`); nothing charged"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"409":{"description":"MOTION_ESTIMATE_CHANGED / stale_estimate: `confirmEmbers` is not the current total (the new estimate is in the body; nothing started)"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"},"503":{"description":"The voice server or render worker is unavailable; nothing charged"}}}},"/api/v2/characters/{id}/storyboards/{sid}/status":{"get":{"tags":["API v2"],"summary":"A storyboard's assembly status","description":"The latest assembly (stage, outputs, per-shot labels, checks), or null before the first one. Needs the read (or admin) scope. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"A storyboard id from GET …/storyboards."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional guard: the character's brand id, or \"personal\"."}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","properties":{"storyboardId":{"type":"string"},"assembly":{"type":"object","nullable":true,"additionalProperties":true}}},"example":{"storyboardId":"k57storyboardone01","assembly":{"stage":"rendering"}}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/characters/{id}/offers":{"get":{"tags":["API v2"],"summary":"What a character's build credit includes","description":"The offer that covers this character: what it includes, what is used and the share of its budget used (0..1), or `included: null` when nothing covers it (everything is charged in Embers). Offers are managed in the dashboard only. Needs the read (or admin) scope. Character Studio and the motion library are staged features: a key whose owner does not have both gets 403.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A character id from GET /api/v2/characters."},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional guard: the character's brand id, or \"personal\"."}],"responses":{"200":{"description":"Included","content":{"application/json":{"schema":{"type":"object","properties":{"characterId":{"type":"string"},"included":{"type":"object","properties":{"offerLabel":{"type":"string"},"kind":{"type":"string","enum":["flat","pack"]},"pooled":{"type":"boolean"},"charactersTotal":{"type":"integer"},"charactersUsed":{"type":"integer"},"holdsCharacter":{"type":"boolean"},"rows":{"type":"array","nullable":true,"items":{"type":"object","description":"An included item.","additionalProperties":true}},"usage":{"type":"array","items":{"type":"object","description":"Used so far.","additionalProperties":true}},"budgetUsed":{"type":"number","minimum":0,"maximum":1},"capsNote":{"type":"string"}},"nullable":true}}},"example":{"characterId":"k57characterember","included":{"offerLabel":"Character pack","kind":"pack","pooled":true,"charactersTotal":3,"charactersUsed":1,"holdsCharacter":true,"rows":[],"usage":[],"budgetUsed":0.25,"capsNote":"Caps limit what the price includes, never what you can do: past a cap everything continues at normal Embers, with a notice before the first charge."}}}}},"400":{"description":"Unreadable JSON body"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Wrong scope, Character Studio or the motion library not enabled, or a bound key naming another brand"},"404":{"description":"CHARACTER_NOT_FOUND (another owner's or brand's character reads the same), MOTION_CLIP_NOT_FOUND or STORYBOARD_NOT_FOUND"},"422":{"description":"Validation: the body names the `field` (code invalid_request); over a limit is refused, never cut"},"429":{"description":"Rate limited or monthly quota exceeded"}}}},"/api/v2/automations/reshare-rules":{"get":{"tags":["API v2"],"summary":"List share rules","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"description":"\"When <account> publishes, reshare to <accounts> after N minutes with comment T\" (or comment on it).","responses":{"200":{"description":"The rules","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string"},"name":{"type":"string","maxLength":120,"example":"Dostal Tech video → founder LinkedIn"},"enabled":{"type":"boolean","default":true},"kind":{"type":"string","enum":["reshare","comment"],"default":"reshare","description":"`reshare`: share the post to `targets`. `comment`: comment on the post itself through the source account."},"sourceAccountIds":{"type":"array","items":{"type":"string"},"description":"Fires when a post goes live through any of these connected accounts."},"sourceLabel":{"type":"string","nullable":true,"example":"type:video","description":"Only posts carrying this label."},"targets":{"type":"array","items":{"type":"object","required":["accountId","platform"],"properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"linkedin"}}}},"template":{"type":"string","description":"The reshare commentary or comment text. Tokens, resolved only once the URL exists: `{{postUrl}}` (this post, on the comment's platform), `{{postUrl:<platform>}}`, `{{parentPostUrl:<post or draft id>}}` (another flayr post: same platform, else YouTube, else any), `{{youtubeUrl:<post or draft id>}}`."},"delayMinutes":{"type":"integer","minimum":0,"default":0,"example":120},"approval":{"type":"string","enum":["needs_approval","auto"],"default":"needs_approval","description":"`needs_approval` (default): each fire waits for a person (POST …/actions/{id} `approve`). `auto`: runs on its own."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"}}},"post":{"tags":["API v2"],"summary":"Create a share rule","security":[{"bearerAuth":[]}],"description":"Needs the `publish` scope (same bar as posting queues). Every account id must be one the key's owner can post through (403 otherwise). Fires from the post.published webhook / status sync, at most once per source post per target account. linkedin: Native reshare with your text (no media/poll); comments yes. twitter: Quote your own posts; otherwise retweet (no text); comments yes. facebook: Link share (no native Share API); comments yes. instagram: Link share (no repost API); comments yes. threads: Link share (no repost API); comments yes. bluesky: Link share (no repost API in Zernio); comments yes. youtube: Link share (no repost API); comments yes. tiktok: Link share (no repost API); comments unverified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","sourceAccountIds"],"properties":{"name":{"type":"string","maxLength":120,"example":"Dostal Tech video → founder LinkedIn"},"enabled":{"type":"boolean","default":true},"kind":{"type":"string","enum":["reshare","comment"],"default":"reshare","description":"`reshare`: share the post to `targets`. `comment`: comment on the post itself through the source account."},"sourceAccountIds":{"type":"array","items":{"type":"string"},"description":"Fires when a post goes live through any of these connected accounts."},"sourceLabel":{"type":"string","nullable":true,"example":"type:video","description":"Only posts carrying this label."},"targets":{"type":"array","items":{"type":"object","required":["accountId","platform"],"properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"linkedin"}}}},"template":{"type":"string","description":"The reshare commentary or comment text. Tokens, resolved only once the URL exists: `{{postUrl}}` (this post, on the comment's platform), `{{postUrl:<platform>}}`, `{{parentPostUrl:<post or draft id>}}` (another flayr post: same platform, else YouTube, else any), `{{youtubeUrl:<post or draft id>}}`."},"delayMinutes":{"type":"integer","minimum":0,"default":0,"example":120},"approval":{"type":"string","enum":["needs_approval","auto"],"default":"needs_approval","description":"`needs_approval` (default): each fire waits for a person (POST …/actions/{id} `approve`). `auto`: runs on its own."},"brandId":{"type":"string"}}}}}},"responses":{"201":{"description":"The rule","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string"},"name":{"type":"string","maxLength":120,"example":"Dostal Tech video → founder LinkedIn"},"enabled":{"type":"boolean","default":true},"kind":{"type":"string","enum":["reshare","comment"],"default":"reshare","description":"`reshare`: share the post to `targets`. `comment`: comment on the post itself through the source account."},"sourceAccountIds":{"type":"array","items":{"type":"string"},"description":"Fires when a post goes live through any of these connected accounts."},"sourceLabel":{"type":"string","nullable":true,"example":"type:video","description":"Only posts carrying this label."},"targets":{"type":"array","items":{"type":"object","required":["accountId","platform"],"properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"linkedin"}}}},"template":{"type":"string","description":"The reshare commentary or comment text. Tokens, resolved only once the URL exists: `{{postUrl}}` (this post, on the comment's platform), `{{postUrl:<platform>}}`, `{{parentPostUrl:<post or draft id>}}` (another flayr post: same platform, else YouTube, else any), `{{youtubeUrl:<post or draft id>}}`."},"delayMinutes":{"type":"integer","minimum":0,"default":0,"example":120},"approval":{"type":"string","enum":["needs_approval","auto"],"default":"needs_approval","description":"`needs_approval` (default): each fire waits for a person (POST …/actions/{id} `approve`). `auto`: runs on its own."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"},"422":{"description":"Invalid rule"}}}},"/api/v2/automations/reshare-rules/{id}":{"get":{"tags":["API v2"],"summary":"Get a share rule","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"responses":{"200":{"description":"The rule","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string"},"name":{"type":"string","maxLength":120,"example":"Dostal Tech video → founder LinkedIn"},"enabled":{"type":"boolean","default":true},"kind":{"type":"string","enum":["reshare","comment"],"default":"reshare","description":"`reshare`: share the post to `targets`. `comment`: comment on the post itself through the source account."},"sourceAccountIds":{"type":"array","items":{"type":"string"},"description":"Fires when a post goes live through any of these connected accounts."},"sourceLabel":{"type":"string","nullable":true,"example":"type:video","description":"Only posts carrying this label."},"targets":{"type":"array","items":{"type":"object","required":["accountId","platform"],"properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"linkedin"}}}},"template":{"type":"string","description":"The reshare commentary or comment text. Tokens, resolved only once the URL exists: `{{postUrl}}` (this post, on the comment's platform), `{{postUrl:<platform>}}`, `{{parentPostUrl:<post or draft id>}}` (another flayr post: same platform, else YouTube, else any), `{{youtubeUrl:<post or draft id>}}`."},"delayMinutes":{"type":"integer","minimum":0,"default":0,"example":120},"approval":{"type":"string","enum":["needs_approval","auto"],"default":"needs_approval","description":"`needs_approval` (default): each fire waits for a person (POST …/actions/{id} `approve`). `auto`: runs on its own."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"}}},"patch":{"tags":["API v2"],"summary":"Update a share rule","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Needs the `publish` scope (same bar as posting queues). Every account id must be one the key's owner can post through (403 otherwise).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120,"example":"Dostal Tech video → founder LinkedIn"},"enabled":{"type":"boolean","default":true},"kind":{"type":"string","enum":["reshare","comment"],"default":"reshare","description":"`reshare`: share the post to `targets`. `comment`: comment on the post itself through the source account."},"sourceAccountIds":{"type":"array","items":{"type":"string"},"description":"Fires when a post goes live through any of these connected accounts."},"sourceLabel":{"type":"string","nullable":true,"example":"type:video","description":"Only posts carrying this label."},"targets":{"type":"array","items":{"type":"object","required":["accountId","platform"],"properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"linkedin"}}}},"template":{"type":"string","description":"The reshare commentary or comment text. Tokens, resolved only once the URL exists: `{{postUrl}}` (this post, on the comment's platform), `{{postUrl:<platform>}}`, `{{parentPostUrl:<post or draft id>}}` (another flayr post: same platform, else YouTube, else any), `{{youtubeUrl:<post or draft id>}}`."},"delayMinutes":{"type":"integer","minimum":0,"default":0,"example":120},"approval":{"type":"string","enum":["needs_approval","auto"],"default":"needs_approval","description":"`needs_approval` (default): each fire waits for a person (POST …/actions/{id} `approve`). `auto`: runs on its own."},"brandId":{"type":"string"}}}}}},"responses":{"200":{"description":"The rule","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string"},"name":{"type":"string","maxLength":120,"example":"Dostal Tech video → founder LinkedIn"},"enabled":{"type":"boolean","default":true},"kind":{"type":"string","enum":["reshare","comment"],"default":"reshare","description":"`reshare`: share the post to `targets`. `comment`: comment on the post itself through the source account."},"sourceAccountIds":{"type":"array","items":{"type":"string"},"description":"Fires when a post goes live through any of these connected accounts."},"sourceLabel":{"type":"string","nullable":true,"example":"type:video","description":"Only posts carrying this label."},"targets":{"type":"array","items":{"type":"object","required":["accountId","platform"],"properties":{"accountId":{"type":"string"},"platform":{"type":"string","example":"linkedin"}}}},"template":{"type":"string","description":"The reshare commentary or comment text. Tokens, resolved only once the URL exists: `{{postUrl}}` (this post, on the comment's platform), `{{postUrl:<platform>}}`, `{{parentPostUrl:<post or draft id>}}` (another flayr post: same platform, else YouTube, else any), `{{youtubeUrl:<post or draft id>}}`."},"delayMinutes":{"type":"integer","minimum":0,"default":0,"example":120},"approval":{"type":"string","enum":["needs_approval","auto"],"default":"needs_approval","description":"`needs_approval` (default): each fire waits for a person (POST …/actions/{id} `approve`). `auto`: runs on its own."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"},"422":{"description":"Invalid rule"}}},"delete":{"tags":["API v2"],"summary":"Delete a share rule","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."}],"description":"Its reshares still waiting (or waiting for approval) are cancelled; sent ones stay as history.","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"string"}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"}}}},"/api/v2/automations/actions":{"get":{"tags":["API v2"],"summary":"List publish actions (comments after publish, reshares)","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard; required once the account is in more than one organization). A brand-bound key always uses its own brand."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["waiting","needs_approval","sending","sent","failed","cancelled","rejected"]}}],"responses":{"200":{"description":"Newest first","content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object","description":"One thing flayr does once a post is live. linkedin: Native reshare with your text (no media/poll); comments yes. twitter: Quote your own posts; otherwise retweet (no text); comments yes. facebook: Link share (no native Share API); comments yes. instagram: Link share (no repost API); comments yes. threads: Link share (no repost API); comments yes. bluesky: Link share (no repost API in Zernio); comments yes. youtube: Link share (no repost API); comments yes. tiktok: Link share (no repost API); comments unverified. X calls are billed per call by Zernio: a post or quote at the create rate (documented $0.015); a link inside a tweet at the URL rate (documented $0.20); retweets are billed per call too.","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["comment","reshare"]},"origin":{"type":"string","enum":["composer","manual","rule","api"]},"status":{"type":"string","enum":["waiting","needs_approval","sending","sent","failed","cancelled","rejected"]},"platform":{"type":"string"},"accountId":{"type":"string"},"template":{"type":"string"},"text":{"type":"string","nullable":true,"description":"The text with tokens filled, once resolved."},"method":{"type":"string","nullable":true,"enum":["linkedin_reshare","x_quote","x_retweet","link_post",null],"description":"`link_post`: the platform has no native repost, so a new post carries the original's link."},"approval":{"type":"string","enum":["needs_approval","auto"]},"waitingOn":{"type":"array","items":{"type":"string"}},"dueAt":{"type":"string","format":"date-time","nullable":true},"delayMinutes":{"type":"integer","nullable":true},"sendAt":{"type":"string","format":"date-time","nullable":true},"attempts":{"type":"integer"},"lastError":{"type":"string","nullable":true},"sentAt":{"type":"string","format":"date-time","nullable":true},"result":{"type":"object","nullable":true,"properties":{"zernioPostId":{"type":"string"},"postId":{"type":"string"},"commentId":{"type":"string"},"url":{"type":"string"}}},"ruleId":{"type":"string","nullable":true},"post":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"urls":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string"}}}}}},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"}}}},"/api/v2/automations/actions/{id}":{"get":{"tags":["API v2"],"summary":"Get a publish action","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The action","content":{"application/json":{"schema":{"type":"object","description":"One thing flayr does once a post is live. linkedin: Native reshare with your text (no media/poll); comments yes. twitter: Quote your own posts; otherwise retweet (no text); comments yes. facebook: Link share (no native Share API); comments yes. instagram: Link share (no repost API); comments yes. threads: Link share (no repost API); comments yes. bluesky: Link share (no repost API in Zernio); comments yes. youtube: Link share (no repost API); comments yes. tiktok: Link share (no repost API); comments unverified. X calls are billed per call by Zernio: a post or quote at the create rate (documented $0.015); a link inside a tweet at the URL rate (documented $0.20); retweets are billed per call too.","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["comment","reshare"]},"origin":{"type":"string","enum":["composer","manual","rule","api"]},"status":{"type":"string","enum":["waiting","needs_approval","sending","sent","failed","cancelled","rejected"]},"platform":{"type":"string"},"accountId":{"type":"string"},"template":{"type":"string"},"text":{"type":"string","nullable":true,"description":"The text with tokens filled, once resolved."},"method":{"type":"string","nullable":true,"enum":["linkedin_reshare","x_quote","x_retweet","link_post",null],"description":"`link_post`: the platform has no native repost, so a new post carries the original's link."},"approval":{"type":"string","enum":["needs_approval","auto"]},"waitingOn":{"type":"array","items":{"type":"string"}},"dueAt":{"type":"string","format":"date-time","nullable":true},"delayMinutes":{"type":"integer","nullable":true},"sendAt":{"type":"string","format":"date-time","nullable":true},"attempts":{"type":"integer"},"lastError":{"type":"string","nullable":true},"sentAt":{"type":"string","format":"date-time","nullable":true},"result":{"type":"object","nullable":true,"properties":{"zernioPostId":{"type":"string"},"postId":{"type":"string"},"commentId":{"type":"string"},"url":{"type":"string"}}},"ruleId":{"type":"string","nullable":true},"post":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"urls":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string"}}}}}},"createdAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"}}},"post":{"tags":["API v2"],"summary":"Approve, reject, retry or cancel a publish action","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"`approve` / `reject`: a rule's action waiting for approval. `retry`: a failed (flagged) one, sent again with the same Idempotency-Key. `cancel`: anything not sent yet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["op"],"properties":{"op":{"type":"string","enum":["approve","reject","retry","cancel"]}}}}}},"responses":{"200":{"description":"The action","content":{"application/json":{"schema":{"type":"object","description":"One thing flayr does once a post is live. linkedin: Native reshare with your text (no media/poll); comments yes. twitter: Quote your own posts; otherwise retweet (no text); comments yes. facebook: Link share (no native Share API); comments yes. instagram: Link share (no repost API); comments yes. threads: Link share (no repost API); comments yes. bluesky: Link share (no repost API in Zernio); comments yes. youtube: Link share (no repost API); comments yes. tiktok: Link share (no repost API); comments unverified. X calls are billed per call by Zernio: a post or quote at the create rate (documented $0.015); a link inside a tweet at the URL rate (documented $0.20); retweets are billed per call too.","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["comment","reshare"]},"origin":{"type":"string","enum":["composer","manual","rule","api"]},"status":{"type":"string","enum":["waiting","needs_approval","sending","sent","failed","cancelled","rejected"]},"platform":{"type":"string"},"accountId":{"type":"string"},"template":{"type":"string"},"text":{"type":"string","nullable":true,"description":"The text with tokens filled, once resolved."},"method":{"type":"string","nullable":true,"enum":["linkedin_reshare","x_quote","x_retweet","link_post",null],"description":"`link_post`: the platform has no native repost, so a new post carries the original's link."},"approval":{"type":"string","enum":["needs_approval","auto"]},"waitingOn":{"type":"array","items":{"type":"string"}},"dueAt":{"type":"string","format":"date-time","nullable":true},"delayMinutes":{"type":"integer","nullable":true},"sendAt":{"type":"string","format":"date-time","nullable":true},"attempts":{"type":"integer"},"lastError":{"type":"string","nullable":true},"sentAt":{"type":"string","format":"date-time","nullable":true},"result":{"type":"object","nullable":true,"properties":{"zernioPostId":{"type":"string"},"postId":{"type":"string"},"commentId":{"type":"string"},"url":{"type":"string"}}},"ruleId":{"type":"string","nullable":true},"post":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"urls":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string"}}}}}},"createdAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"},"422":{"description":"Not allowed in its state"}}}},"/api/v2/posts/{id}/comments":{"get":{"tags":["API v2"],"summary":"List a post's comments after publish and reshares","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The actions","content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object","description":"One thing flayr does once a post is live. linkedin: Native reshare with your text (no media/poll); comments yes. twitter: Quote your own posts; otherwise retweet (no text); comments yes. facebook: Link share (no native Share API); comments yes. instagram: Link share (no repost API); comments yes. threads: Link share (no repost API); comments yes. bluesky: Link share (no repost API in Zernio); comments yes. youtube: Link share (no repost API); comments yes. tiktok: Link share (no repost API); comments unverified. X calls are billed per call by Zernio: a post or quote at the create rate (documented $0.015); a link inside a tweet at the URL rate (documented $0.20); retweets are billed per call too.","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["comment","reshare"]},"origin":{"type":"string","enum":["composer","manual","rule","api"]},"status":{"type":"string","enum":["waiting","needs_approval","sending","sent","failed","cancelled","rejected"]},"platform":{"type":"string"},"accountId":{"type":"string"},"template":{"type":"string"},"text":{"type":"string","nullable":true,"description":"The text with tokens filled, once resolved."},"method":{"type":"string","nullable":true,"enum":["linkedin_reshare","x_quote","x_retweet","link_post",null],"description":"`link_post`: the platform has no native repost, so a new post carries the original's link."},"approval":{"type":"string","enum":["needs_approval","auto"]},"waitingOn":{"type":"array","items":{"type":"string"}},"dueAt":{"type":"string","format":"date-time","nullable":true},"delayMinutes":{"type":"integer","nullable":true},"sendAt":{"type":"string","format":"date-time","nullable":true},"attempts":{"type":"integer"},"lastError":{"type":"string","nullable":true},"sentAt":{"type":"string","format":"date-time","nullable":true},"result":{"type":"object","nullable":true,"properties":{"zernioPostId":{"type":"string"},"postId":{"type":"string"},"commentId":{"type":"string"},"url":{"type":"string"}}},"ruleId":{"type":"string","nullable":true},"post":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"urls":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string"}}}}}},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"}}},"post":{"tags":["API v2"],"summary":"Add comments after publish to a post","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Needs the `publish` scope (same bar as posting queues). Every account id must be one the key's owner can post through (403 otherwise). Each comment is sent once (Zernio Idempotency-Key), after the post is live on that platform, its tokens resolve, `delayMinutes` have passed and `sendAt` is reached. Tokens, resolved only once the URL exists: `{{postUrl}}` (this post, on the comment's platform), `{{postUrl:<platform>}}`, `{{parentPostUrl:<post or draft id>}}` (another flayr post: same platform, else YouTube, else any), `{{youtubeUrl:<post or draft id>}}`. TikTok comments work only for TikTok for Business accounts (unverified); a comment that cannot be sent is flagged `failed` and can be retried.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["comments"],"properties":{"comments":{"type":"array","maxItems":20,"items":{"type":"object","required":["platform","text"],"properties":{"platform":{"type":"string","example":"linkedin"},"text":{"type":"string","example":"Full video: {{youtubeUrl:k17abc…}}"},"accountId":{"type":"string","description":"Default: the account the post went out through on that platform."},"delayMinutes":{"type":"integer","minimum":0},"sendAt":{"type":"string","format":"date-time","description":"Not before this time."}}}}}}}}},"responses":{"201":{"description":"The new actions","content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object","description":"One thing flayr does once a post is live. linkedin: Native reshare with your text (no media/poll); comments yes. twitter: Quote your own posts; otherwise retweet (no text); comments yes. facebook: Link share (no native Share API); comments yes. instagram: Link share (no repost API); comments yes. threads: Link share (no repost API); comments yes. bluesky: Link share (no repost API in Zernio); comments yes. youtube: Link share (no repost API); comments yes. tiktok: Link share (no repost API); comments unverified. X calls are billed per call by Zernio: a post or quote at the create rate (documented $0.015); a link inside a tweet at the URL rate (documented $0.20); retweets are billed per call too.","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["comment","reshare"]},"origin":{"type":"string","enum":["composer","manual","rule","api"]},"status":{"type":"string","enum":["waiting","needs_approval","sending","sent","failed","cancelled","rejected"]},"platform":{"type":"string"},"accountId":{"type":"string"},"template":{"type":"string"},"text":{"type":"string","nullable":true,"description":"The text with tokens filled, once resolved."},"method":{"type":"string","nullable":true,"enum":["linkedin_reshare","x_quote","x_retweet","link_post",null],"description":"`link_post`: the platform has no native repost, so a new post carries the original's link."},"approval":{"type":"string","enum":["needs_approval","auto"]},"waitingOn":{"type":"array","items":{"type":"string"}},"dueAt":{"type":"string","format":"date-time","nullable":true},"delayMinutes":{"type":"integer","nullable":true},"sendAt":{"type":"string","format":"date-time","nullable":true},"attempts":{"type":"integer"},"lastError":{"type":"string","nullable":true},"sentAt":{"type":"string","format":"date-time","nullable":true},"result":{"type":"object","nullable":true,"properties":{"zernioPostId":{"type":"string"},"postId":{"type":"string"},"commentId":{"type":"string"},"url":{"type":"string"}}},"ruleId":{"type":"string","nullable":true},"post":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"urls":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string"}}}}}},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Invalid API key"},"403":{"description":"Scope / brand / account not allowed"},"404":{"description":"Not found"},"422":{"description":"Invalid comment"}}}},"/api/v2/frames":{"get":{"tags":["API v2"],"summary":"List frames","description":"The brand's frame library (`frames`) and the built-in flayr frames (`defaults`, drawn in the brand colors). Any `ref` can be applied with POST /api/v2/frames/apply.","security":[{"bearerAuth":[]}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"]}},{"name":"aspect","in":"query","required":false,"schema":{"type":"string","enum":["1:1","4:5","9:16","16:9"]}},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Frames","content":{"application/json":{"schema":{"type":"object","properties":{"frames":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","description":"`brand:<id>` — pass as frameRef to apply."},"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"]},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["upload","default_fork","import"]},"defaultKey":{"type":"string"},"rights":{"type":"string","nullable":true,"enum":["original","owned","licensed",null],"description":"null = not confirmed yet (never blocks)."},"archived":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"]},"width":{"type":"integer"},"height":{"type":"integer"},"contentBox":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"safeArea":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"fit":{"type":"string","enum":["cover","contain"]},"url":{"type":"string","nullable":true}}}}}}},"defaults":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","description":"`default:<key>`"},"name":{"type":"string"},"kind":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"]},"tags":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"aspects":{"type":"array","items":{"type":"string","enum":["1:1","4:5","9:16","16:9"]}},"texts":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"post":{"tags":["API v2"],"summary":"Add a frame to the library","description":"Either copy a flayr frame (`defaultKey`, optional colors and texts) or add your own art (`name` + `variants` of uploaded PNG/SVG files). Requires the write scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"defaultKey":{"type":"string","description":"A defaults[].ref without \"default:\"."},"paletteOverride":{"type":"object","description":"Colors that win over the brand kit. Every key is optional; omitted keys fall back to the brand kit palette. Each present key must be a #rrggbb hex.","properties":{"primary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"onPrimary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"paper":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"ink":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}}},"texts":{"type":"object","description":"Texts some frames print (ribbon/tag label, lower-third title/subtitle).","properties":{"label":{"type":"string","maxLength":60},"title":{"type":"string","maxLength":60},"subtitle":{"type":"string","maxLength":60}}},"name":{"type":"string","maxLength":80},"kind":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"],"description":"Default: guessed from the name."},"tags":{"type":"array","maxItems":20,"items":{"type":"string"}},"variants":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["storageId"],"properties":{"storageId":{"type":"string","description":"From POST /api/v2/media/upload-url, then POST the PNG (with transparency) or SVG bytes."},"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"],"description":"Default: nearest to the image size."},"contentBox":{"type":"object","required":["x","y","w","h"],"description":"Default: detected from the transparent area. Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"fit":{"type":"string","enum":["cover","contain"]}}},"description":"One per aspect ratio."},"rights":{"type":"string","enum":["original","owned","licensed"],"description":"Who holds the rights to the art. Optional; a frame without it shows a reminder."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","description":"`brand:<id>` — pass as frameRef to apply."},"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"]},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["upload","default_fork","import"]},"defaultKey":{"type":"string"},"rights":{"type":"string","nullable":true,"enum":["original","owned","licensed",null],"description":"null = not confirmed yet (never blocks)."},"archived":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"]},"width":{"type":"integer"},"height":{"type":"integer"},"contentBox":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"safeArea":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"fit":{"type":"string","enum":["cover","contain"]},"url":{"type":"string","nullable":true}}}}}}}}},"404":{"description":"Unknown defaultKey"},"422":{"description":"Invalid field"}}}},"/api/v2/frames/{id}":{"get":{"tags":["API v2"],"summary":"Get a frame","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Frame","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","description":"`brand:<id>` — pass as frameRef to apply."},"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"]},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["upload","default_fork","import"]},"defaultKey":{"type":"string"},"rights":{"type":"string","nullable":true,"enum":["original","owned","licensed",null],"description":"null = not confirmed yet (never blocks)."},"archived":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"]},"width":{"type":"integer"},"height":{"type":"integer"},"contentBox":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"safeArea":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"fit":{"type":"string","enum":["cover","contain"]},"url":{"type":"string","nullable":true}}}}}}}}},"404":{"description":"Not found"}}},"patch":{"tags":["API v2"],"summary":"Update a frame","description":"Name, kind, tags, rights, archived, or the content area per aspect. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"]},"tags":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"},"rights":{"type":"string","enum":["original","owned","licensed"]},"boxes":{"type":"array","items":{"type":"object","required":["aspect","contentBox"],"properties":{"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"]},"contentBox":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"safeArea":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"fit":{"type":"string","enum":["cover","contain"]}}}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","description":"`brand:<id>` — pass as frameRef to apply."},"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"]},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["upload","default_fork","import"]},"defaultKey":{"type":"string"},"rights":{"type":"string","nullable":true,"enum":["original","owned","licensed",null],"description":"null = not confirmed yet (never blocks)."},"archived":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"]},"width":{"type":"integer"},"height":{"type":"integer"},"contentBox":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"safeArea":{"type":"object","required":["x","y","w","h"],"description":"Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"fit":{"type":"string","enum":["cover","contain"]},"url":{"type":"string","nullable":true}}}}}}}}},"404":{"description":"Not found"},"422":{"description":"Invalid field"}}},"delete":{"tags":["API v2"],"summary":"Delete a frame","description":"Deletes its art. Images already framed keep their pixels. Requires the write scope.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ deleted: id }"},"404":{"description":"Not found"}}}},"/api/v2/frames/apply":{"post":{"tags":["API v2"],"summary":"Frame an image","description":"Draws a frame over an image and returns a NEW image (the source is untouched). Same inputs again return the stored image for free. Priced per new image by the frames admin config (free by default). Requires the write scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceUrl","frameRef"],"properties":{"sourceUrl":{"type":"string","description":"https image URL (flayr/Convex storage or a stock host)."},"frameRef":{"type":"string","description":"`default:<key>` or `brand:<id>` from GET /api/v2/frames."},"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"],"description":"Default: nearest to the source image."},"fit":{"type":"string","enum":["cover","contain"]},"zoom":{"type":"number","minimum":1,"maximum":2},"offsetX":{"type":"number","minimum":-1,"maximum":1},"offsetY":{"type":"number","minimum":-1,"maximum":1},"paletteOverride":{"type":"object","description":"Colors that win over the brand kit. Every key is optional; omitted keys fall back to the brand kit palette. Each present key must be a #rrggbb hex.","properties":{"primary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"onPrimary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"paper":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"ink":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}}},"texts":{"type":"object","description":"Texts some frames print (ribbon/tag label, lower-third title/subtitle).","properties":{"label":{"type":"string","maxLength":60},"title":{"type":"string","maxLength":60},"subtitle":{"type":"string","maxLength":60}}},"platform":{"type":"string","description":"Platform this framed image is for (\"all\" by default)."},"slideIndex":{"type":"integer","minimum":0,"description":"Image position in the post."},"contentId":{"type":"string","description":"A content id: its publish swaps this framed image in for `platform`."}}}}}},"responses":{"200":{"description":"Framed image","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"]},"cached":{"type":"boolean"},"embersCharged":{"type":"integer"}}}}}},"400":{"description":"Source not allowed"},"403":{"description":"Frames are turned off"},"404":{"description":"Unknown frame"},"422":{"description":"Invalid field"}}}},"/api/v2/frames/settings":{"get":{"tags":["API v2"],"summary":"Get auto-frame settings","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"{ autoFrame: { [platform]: { frameRef, aspect? } } }"}}},"post":{"tags":["API v2"],"summary":"Set auto-frame for a platform","description":"Every image posted to `platform` gets this frame when published or scheduled, unless the post picked its own. `frameRef: null` turns it off. Requires the write scope.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","frameRef"],"properties":{"platform":{"type":"string","example":"instagram"},"frameRef":{"type":"string","nullable":true},"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"]}}}}}},"responses":{"200":{"description":"{ autoFrame }"},"422":{"description":"Unknown platform or frame"}}}},"/api/v2/frames/import":{"post":{"tags":["API v2"],"summary":"Bulk-import frames into a brand (flayr admin)","description":"Up to 25 frames per call into `brandId`, grouped under `batchId` (send more with the same batchId). Needs a write-scope key whose owner is a flayr super-admin. Undo with DELETE /api/v2/frames/import/{batchId}.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["brandId","frames"],"properties":{"brandId":{"type":"string"},"batchId":{"type":"string","pattern":"^[A-Za-z0-9_-]{6,64}$"},"frames":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","required":["name","variants"],"properties":{"name":{"type":"string","maxLength":80},"kind":{"type":"string","enum":["border","overlay","lower_third","corner_bug","quote_card","ribbon"],"description":"Default: guessed from the name."},"tags":{"type":"array","maxItems":20,"items":{"type":"string"}},"variants":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["storageId"],"properties":{"storageId":{"type":"string","description":"From POST /api/v2/media/upload-url, then POST the PNG (with transparency) or SVG bytes."},"aspect":{"type":"string","enum":["1:1","4:5","9:16","16:9"],"description":"Default: nearest to the image size."},"contentBox":{"type":"object","required":["x","y","w","h"],"description":"Default: detected from the transparent area. Where the post sits inside the frame, as fractions (0–1) of the frame canvas.","properties":{"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"fit":{"type":"string","enum":["cover","contain"]}}},"description":"One per aspect ratio."},"rights":{"type":"string","enum":["original","owned","licensed"],"description":"Who holds the rights to the art. Optional; a frame without it shows a reminder."}}}}}}}}},"responses":{"201":{"description":"{ batchId, imported, ids }"},"403":{"description":"Not a flayr admin key"},"422":{"description":"Invalid field"}}}},"/api/v2/frames/import/{batchId}":{"delete":{"tags":["API v2"],"summary":"Undo a frames import (flayr admin)","security":[{"bearerAuth":[]}],"parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ removed }"},"403":{"description":"Not a flayr admin key"}}}},"/api/v2/hook-studio/offers":{"post":{"tags":["API v2"],"summary":"Capture offers","description":"Step 1 of Hook Studio. Turns pasted text, or answers to the offer interview, into draft offers in the brand's offer bank, with prices resolved from the plan catalog, Shopify or the text itself. Needs the write scope and the Pro+ plan. Embers: 6 Embers per capture (POST) (default price; refunded when nothing usable comes back); GET and PATCH free.","x-credit-cost":"6 Embers per capture (POST) (default price; refunded when nothing usable comes back); GET and PATCH free","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"text":{"type":"string","maxLength":5000,"description":"What the brand sells, in any words."},"answers":{"type":"array","items":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"source":{"type":"string","enum":["interview","manual"]}}}}}},"responses":{"201":{"description":"Draft offers","content":{"application/json":{"schema":{"type":"object","properties":{"embersCharged":{"type":"integer","description":"Embers charged for this call."},"offers":{"type":"array","items":{"type":"object","description":"A bank item: `id` plus its fields.","additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}}},"402":{"description":"Pro+ plan required, or not enough Embers"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid body, or nothing usable came back (not charged)"},"502":{"description":"The skill failed (not charged)"}}},"get":{"tags":["API v2"],"summary":"List offers","description":"The brand's offer bank. Needs the read scope and the Pro+ plan. Embers: 0 Embers (free, read-only).","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","confirmed","retired"]}}],"responses":{"200":{"description":"Offers","content":{"application/json":{"schema":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","description":"A bank item: `id` plus its fields.","additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid request"}}},"patch":{"tags":["API v2"],"summary":"Update an offer","description":"Changes only the fields sent; `status: \"confirmed\"` marks the offer ready for hooks and CTAs. A manual price is verified by its proof page, never by the caller. Needs the write scope and the Pro+ plan. Embers: 0 Embers (free).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"priceSource":{"type":"string","enum":["plan_catalog","shopify","manual"]},"priceRef":{"type":"string"},"priceAmount":{"type":"number"},"currency":{"type":"string"},"proofUrl":{"type":"string"},"audience":{"type":"string"},"pains":{"type":"array","items":{"type":"string"}},"outcomes":{"type":"array","items":{"type":"string"}},"proof":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","confirmed","retired"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or the item is not in this brand’s bank"},"422":{"description":"Invalid request"}}}},"/api/v2/hook-studio/hooks/generate":{"post":{"tags":["API v2"],"summary":"Generate hooks","description":"Step 2. Writes a batch of draft hooks (on-screen card + spoken line) from the brand's confirmed offers and, optionally, its bodies. Every hook is claims-checked; blocked ones come back in `dropped` and are not saved. Needs the write scope and the Pro+ plan. Embers: 25 Embers per batch (default price; refunded when nothing usable comes back).","x-credit-cost":"25 Embers per batch (default price; refunded when nothing usable comes back)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"angles":{"type":"array","items":{"type":"string"},"description":"e.g. pain, outcome, curiosity, proof."},"formats":{"type":"array","items":{"type":"string"},"description":"e.g. question, bold claim, number, POV."},"count":{"type":"integer","minimum":1,"maximum":20},"topics":{"type":"array","items":{"type":"string"}},"bodyIds":{"type":"array","items":{"type":"string"},"description":"Bodies (from POST /api/v2/hook-studio/bodies/map) the hooks should lead into."}}}}}},"responses":{"201":{"description":"Draft hooks","content":{"application/json":{"schema":{"type":"object","properties":{"embersCharged":{"type":"integer","description":"Embers charged for this call."},"hooks":{"type":"array","items":{"type":"object","description":"A bank item: `id` plus its fields.","additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"}}}},"dropped":{"type":"array","items":{"type":"object"}}}}}}},"402":{"description":"Pro+ plan required, or not enough Embers"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid body, or nothing usable came back (not charged)"},"502":{"description":"The skill failed (not charged)"}}}},"/api/v2/hook-studio/hooks":{"get":{"tags":["API v2"],"summary":"List hooks","description":"The brand's hook bank. Needs the read scope and the Pro+ plan. Embers: 0 Embers (free; PATCH re-runs the claims check at no charge).","x-credit-cost":"0 Embers (free; PATCH re-runs the claims check at no charge)","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","approved","retired"]}}],"responses":{"200":{"description":"Hooks","content":{"application/json":{"schema":{"type":"object","properties":{"hooks":{"type":"array","items":{"type":"object","description":"A bank item: `id` plus its fields.","additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid request"}}},"patch":{"tags":["API v2"],"summary":"Update a hook","description":"Changes only the fields sent. Changing `card` or `line` re-runs the claims check and stores its result (`claims`); a hook whose claims block cannot be approved (422). Needs the write scope and the Pro+ plan. Embers: 0 Embers (free; PATCH re-runs the claims check at no charge).","x-credit-cost":"0 Embers (free; PATCH re-runs the claims check at no charge)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"id":{"type":"string"},"card":{"type":"string"},"line":{"type":"string"},"angle":{"type":"string"},"format":{"type":"string"},"style":{"type":"string","enum":["question","reveal","joke","how-to","hot-take","story"]},"fit":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","approved","retired"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"claims":{"type":"object","properties":{"verdict":{"type":"string","enum":["pass","warn","block"]},"findings":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"severity":{"type":"string","enum":["block","warn"]},"span":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}}},"message":{"type":"string"},"fix":{"type":"string"}}}}},"nullable":true}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or the item is not in this brand’s bank"},"422":{"description":"Invalid request"}}}},"/api/v2/hook-studio/bodies/map":{"post":{"tags":["API v2"],"summary":"Map bodies","description":"Step 3. Maps library clips, Shopify products, features or pasted texts to draft bodies (what each one shows and proves), so hooks can lead into them. Collab clips are skipped unless `includeCollab` is true. Needs the write scope and the Pro+ plan. Embers: 6 Embers per mapping (default price; refunded when nothing usable comes back).","x-credit-cost":"6 Embers per mapping (default price; refunded when nothing usable comes back)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"libraryContentIds":{"type":"array","items":{"type":"string"}},"productGids":{"type":"array","items":{"type":"string"}},"features":{"type":"array","items":{"type":"string"}},"texts":{"type":"array","items":{"type":"string"}},"includeCollab":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Draft bodies","content":{"application/json":{"schema":{"type":"object","properties":{"embersCharged":{"type":"integer","description":"Embers charged for this call."},"bodies":{"type":"array","items":{"type":"object","description":"A bank item: `id` plus its fields.","additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"}}}},"skippedCollab":{"type":"array","items":{"type":"string"}}}}}}},"402":{"description":"Pro+ plan required, or not enough Embers"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid body, or nothing usable came back (not charged)"},"502":{"description":"The skill failed (not charged)"}}}},"/api/v2/hook-studio/ctas/generate":{"post":{"tags":["API v2"],"summary":"Generate CTAs","description":"Step 4. Writes a batch of draft calls to action for the brand's confirmed offers, each claims-checked against where it points. Then mix hooks, bodies and CTAs into posts in the dashboard. Needs the write scope and the Pro+ plan. Embers: 4 Embers per batch (default price; refunded when nothing usable comes back).","x-credit-cost":"4 Embers per batch (default price; refunded when nothing usable comes back)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"offerIds":{"type":"array","items":{"type":"string"}},"count":{"type":"integer","minimum":1,"maximum":20},"destination":{"type":"string","description":"An https link every CTA may point at, or `bio` for link in bio."},"platforms":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Draft CTAs","content":{"application/json":{"schema":{"type":"object","properties":{"embersCharged":{"type":"integer","description":"Embers charged for this call."},"ctas":{"type":"array","items":{"type":"object","description":"A bank item: `id` plus its fields.","additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"}}}},"dropped":{"type":"array","items":{"type":"object"}}}}}}},"402":{"description":"Pro+ plan required, or not enough Embers"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid body, or nothing usable came back (not charged)"},"502":{"description":"The skill failed (not charged)"}}}},"/api/v2/hook-studio/ctas":{"get":{"tags":["API v2"],"summary":"List CTAs","description":"The brand's CTA bank, with each CTA's goal fields. Needs the read scope and the Pro+ plan. Embers: 0 Embers (free; POST and PATCH run the claims check at no charge).","x-credit-cost":"0 Embers (free; POST and PATCH run the claims check at no charge)","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","approved","retired"]}}],"responses":{"200":{"description":"CTAs","content":{"application/json":{"schema":{"type":"object","properties":{"ctas":{"type":"array","items":{"type":"object","description":"A bank item: `id` plus its fields.","additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid request"}}},"post":{"tags":["API v2"],"summary":"Add a CTA","description":"Adds a hand-written CTA to the bank, claims-checked (`claims`); a CTA whose claims block cannot be approved (422). Goal fields only describe which CTA an ad would use; nothing here creates or runs an ad. Needs the write scope and the Pro+ plan. Embers: 0 Embers (free; POST and PATCH run the claims check at no charge).","x-credit-cost":"0 Embers (free; POST and PATCH run the claims check at no charge)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["card","line","destination","platforms"],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"card":{"type":"string"},"line":{"type":"string"},"destination":{"type":"string","description":"An https link, or \"bio\" for the link in bio."},"platforms":{"type":"array","items":{"type":"string"}},"offerId":{"type":"string"},"goalKey":{"type":"string","description":"The goal this CTA serves, a short slug such as `tech-checkup`."},"isPrimary":{"type":"boolean","description":"The brand's primary goal. Setting it demotes the previous primary."},"paidEligible":{"type":"boolean","description":"Ads may use this CTA. Default: true for a primary, false otherwise."},"adButton":{"type":"string","enum":["LEARN_MORE","SIGN_UP","BOOK_NOW","WATCH_MORE","SHOP_NOW","CONTACT_US","SUBSCRIBE","GET_OFFER","GET_QUOTE","APPLY_NOW","DOWNLOAD","ORDER_NOW"],"description":"The ad button. Default: the ads config default CTA."},"status":{"type":"string","enum":["draft","approved"]}}}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"claims":{"type":"object","properties":{"verdict":{"type":"string","enum":["pass","warn","block"]},"findings":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"severity":{"type":"string","enum":["block","warn"]},"span":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}}},"message":{"type":"string"},"fix":{"type":"string"}}}}}}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or the item is not in this brand’s bank"},"422":{"description":"Invalid request"}}},"patch":{"tags":["API v2"],"summary":"Update a CTA","description":"Changes only the fields sent. Changing `card`, `line`, `destination` or `platforms` re-runs the claims check. Goal fields only describe which CTA an ad would use; nothing here creates or runs an ad. Needs the write scope and the Pro+ plan. Embers: 0 Embers (free; POST and PATCH run the claims check at no charge).","x-credit-cost":"0 Embers (free; POST and PATCH run the claims check at no charge)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"id":{"type":"string"},"card":{"type":"string"},"line":{"type":"string"},"destination":{"type":"string","description":"An https link, or \"bio\" for the link in bio."},"platforms":{"type":"array","items":{"type":"string"}},"offerId":{"type":"string"},"goalKey":{"type":"string","description":"The goal this CTA serves, a short slug such as `tech-checkup`."},"isPrimary":{"type":"boolean","description":"The brand's primary goal. Setting it demotes the previous primary."},"paidEligible":{"type":"boolean","description":"Ads may use this CTA. Default: true for a primary, false otherwise."},"adButton":{"type":"string","enum":["LEARN_MORE","SIGN_UP","BOOK_NOW","WATCH_MORE","SHOP_NOW","CONTACT_US","SUBSCRIBE","GET_OFFER","GET_QUOTE","APPLY_NOW","DOWNLOAD","ORDER_NOW"],"description":"The ad button. Default: the ads config default CTA."},"status":{"type":"string","enum":["draft","approved","retired"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"claims":{"type":"object","properties":{"verdict":{"type":"string","enum":["pass","warn","block"]},"findings":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"severity":{"type":"string","enum":["block","warn"]},"span":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}}},"message":{"type":"string"},"fix":{"type":"string"}}}}},"nullable":true}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or the item is not in this brand’s bank"},"422":{"description":"Invalid request"}}}},"/api/v2/hook-studio/cta-settings":{"get":{"tags":["API v2"],"summary":"Goals and CTA check settings","description":"The brand's goals (`goals.source`: `tagged`, `implicit` from the brand website, or `none`) and its CTA check settings. Goal fields only describe which CTA an ad would use; nothing here creates or runs an ad. Needs the read scope and the Pro+ plan. Embers: 0 Embers (free).","x-credit-cost":"0 Embers (free)","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."}}],"responses":{"200":{"description":"Goals and settings","content":{"application/json":{"schema":{"type":"object","properties":{"goals":{"type":"object"},"settings":{"type":"object","properties":{"ctaLevel":{"type":"string","enum":["off","warn","block"],"description":"The CTA check on organic posts. Default: warn."},"ctaPaidLevel":{"type":"string","enum":["warn","block"],"description":"The CTA check on paid posts, never off. Default: block."},"organicSupportingHosts":{"type":"array","items":{"type":"string"},"description":"Hosts an organic post may link to besides a goal. Default: the website, youtube.com, youtu.be, github.com."},"autoApplyPrimaryCta":{"type":"boolean","description":"Studio adds the primary CTA to a post with none. Default: true."}}},"canEdit":{"type":"boolean"}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid request"}}},"patch":{"tags":["API v2"],"summary":"Update CTA check settings","description":"Changes only the fields sent; the other post quality checks are kept. Owners and admins only (403 otherwise). Needs the write scope and the Pro+ plan. Embers: 0 Embers (free).","x-credit-cost":"0 Embers (free)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"ctaLevel":{"type":"string","enum":["off","warn","block"],"description":"The CTA check on organic posts. Default: warn."},"ctaPaidLevel":{"type":"string","enum":["warn","block"],"description":"The CTA check on paid posts, never off. Default: block."},"organicSupportingHosts":{"type":"array","items":{"type":"string"},"description":"Hosts an organic post may link to besides a goal. Default: the website, youtube.com, youtu.be, github.com."},"autoApplyPrimaryCta":{"type":"boolean","description":"Studio adds the primary CTA to a post with none. Default: true."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"ctaLevel":{"type":"string","enum":["off","warn","block"],"description":"The CTA check on organic posts. Default: warn."},"ctaPaidLevel":{"type":"string","enum":["warn","block"],"description":"The CTA check on paid posts, never off. Default: block."},"organicSupportingHosts":{"type":"array","items":{"type":"string"},"description":"Hosts an organic post may link to besides a goal. Default: the website, youtube.com, youtu.be, github.com."},"autoApplyPrimaryCta":{"type":"boolean","description":"Studio adds the primary CTA to a post with none. Default: true."}}}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid request"}}}},"/api/v2/hook-studio/claims/check":{"post":{"tags":["API v2"],"summary":"Check claims","description":"Checks copy against the brand's claims sources (verified prices, banned phrases, competitors, destinations) before it is used. No model call, nothing stored. Needs the read scope and the Pro+ plan. Embers: 0 Embers (free, read-only).","x-credit-cost":"0 Embers (free, read-only)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","context"],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"text":{"type":"string","maxLength":5000},"context":{"type":"string","enum":["hook","cta","caption","ad"]},"destination":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Claims result","content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["pass","warn","block"]},"findings":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"severity":{"type":"string","enum":["block","warn"]},"span":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}}},"message":{"type":"string"},"fix":{"type":"string"}}}}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or not a member of it"},"422":{"description":"Invalid request"}}}},"/api/v2/cta-check":{"post":{"tags":["API v2"],"summary":"Check a CTA before an ad","description":"Runs the CTA check on a draft, a post or a link: does it point at the brand's goal page? Paid mode (the default) is what /api/ads/create, /api/ads/boost and the ad-set ads route run; a block there answers 409 with the same findings. Run this before every boost or ad. `fix` is the brand's paid-eligible primary goal (link and button). Nothing stored, nothing created. Needs the read scope and the Pro+ plan. Embers: 0 Embers (free, read-only).","x-credit-cost":"0 Embers (free, read-only)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"brandId":{"type":"string","description":"A brand id from GET /api/v2/brands. Required for an account-wide key; a brand-bound key may omit it."},"contentId":{"type":"string","description":"A draft id."},"postId":{"type":"string","description":"A post id."},"linkUrl":{"type":"string","description":"The link the ad or post would use."},"platforms":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["paid","organic"],"description":"Default: paid."},"objective":{"type":"string","description":"The ad objective, e.g. traffic, link_clicks, engagement. Click objectives can block; others warn."},"adButton":{"type":"string","description":"The ad button, e.g. LEARN_MORE."},"caption":{"type":"string","description":"The caption, when it differs from the draft."}}}}}},"responses":{"200":{"description":"CTA result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"string","enum":["ok","warn","block"]},"findings":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["block","warn"]},"message":{"type":"string"},"url":{"type":"string"}}}},"fix":{"type":"object","nullable":true,"properties":{"linkUrl":{"type":"string"},"adButton":{"type":"string"},"goalKey":{"type":"string"}}},"mode":{"type":"string","enum":["paid","organic"]}}}}}},"402":{"description":"Pro+ plan required"},"403":{"description":"Missing scope, or a brand-bound key naming another brand"},"404":{"description":"Unknown brand, or the draft or post is not in this brand"},"422":{"description":"Invalid request"}}}},"/api/v2/ads/destinations":{"get":{"tags":["API v2"],"summary":"List landing destinations","security":[{"bearerAuth":[]}],"description":"Enabled landing registry choices and whether the active brand/ad account requires them. Send the selected destinationId when creating a Flayr campaign.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"responses":{"200":{"description":"Destination policy","content":{"application/json":{"schema":{"type":"object","properties":{"required":{"type":"boolean"},"origin":{"type":"string"},"adDestinations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"label":{"type":"string"},"enabled":{"type":"boolean"},"variant":{"type":"string","nullable":true,"enum":["current","v4",null]},"tab":{"type":"string","nullable":true,"enum":["small-business","shops","marketing-teams","creators",null]}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}}},"/api/v2/ads/accounts":{"get":{"tags":["API v2"],"summary":"List ad accounts","security":[{"bearerAuth":[]}],"description":"The brand's selected ad accounts, one per ad network (Meta, LinkedIn, TikTok, Google, ...), newest pick first, each with its spend limit, balance and readiness.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"responses":{"200":{"description":"Ad accounts","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","description":"Ad network family: meta (facebook, instagram, metaads), linkedin, tiktok, google, x, reddit, pinterest, microsoft, openai."},"brandId":{"type":"string"},"platform":{"type":"string"},"platformAdAccountId":{"type":"string"},"currency":{"type":"string"},"spendLimitMinor":{"type":"integer","nullable":true},"balanceMinor":{"type":"integer","nullable":true},"readiness":{"type":"string","enum":["ready","needs_action","pending","check","not_connected"],"nullable":true}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}},"post":{"tags":["API v2"],"summary":"Select the ad account for one network","security":[{"bearerAuth":[]}],"description":"Needs a key with the ads:manage scope. Stores the ad account for the platform's network only; other networks keep their selection. The account must be visible to a login connected to the brand on that network and use USD.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","platformAdAccountId"],"properties":{"platform":{"type":"string","description":"e.g. facebook, linkedin, tiktokads, googleads"},"platformAdAccountId":{"type":"string"}}}}}},"responses":{"200":{"description":"Selected","content":{"application/json":{"schema":{"type":"object","properties":{"selected":{"type":"boolean"},"network":{"type":"string"},"platform":{"type":"string"},"platformAdAccountId":{"type":"string"}}}}}},"400":{"description":"Invalid body, or not a USD account"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks ads:manage, ads not available, or another brand for a brand-bound key"},"404":{"description":"No connected login on that network can use this ad account, or unknown brand"},"502":{"description":"The ad network could not verify the account"}}}},"/api/v2/ads/campaigns":{"get":{"tags":["API v2"],"summary":"List ad campaigns","security":[{"bearerAuth":[]}],"description":"The brand's campaigns with ad sets, ads, dates, max spend and spend to date.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."},{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"e.g. active, paused"},{"name":"platform","in":"query","required":false,"schema":{"type":"string"},"description":"e.g. facebook, instagram"}],"responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Flayr campaign id (the one pause/stop take)."},"provenance":{"type":"object","description":"Present when this row has import metadata.","required":["source","importedAt"],"properties":{"source":{"type":"string","enum":["sync","backfill","import"]},"importedAt":{"type":"number","description":"Import timestamp in Unix milliseconds."},"importBatchId":{"type":"string"},"sourceRef":{"type":"string","description":"Source API window or file and row reference."}}},"platform":{"type":"string"},"platformCampaignId":{"type":"string","nullable":true,"description":"The ad network's own campaign id, when known."},"name":{"type":"string"},"status":{"type":"string","description":"The vendor's normalized status. It can read error for network states that are not failures; read platformStatus for the real state."},"platformStatus":{"type":"string","nullable":true,"description":"FFE-1607: the network's raw campaign status (TikTok secondary_status such as CAMPAIGN_STATUS_NOT_START); null when the network sent none."},"sync":{"type":"object","description":"FFE-1607: whether status and the ad sets come from the network yet. never = only flayr's create record exists (status is the PAUSED hold flayr asked for, adSets are empty until the first sync).","properties":{"state":{"type":"string","enum":["synced","never"]},"lastSeenAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"objective":{"type":"string","nullable":true},"budget":{"type":"object","properties":{"type":{"type":"string","enum":["daily","lifetime"],"nullable":true},"amountMinor":{"type":"integer","nullable":true},"currency":{"type":"string","nullable":true},"source":{"type":"string","enum":["network","flayr_total"],"nullable":true,"description":"FFE-1607: network = the network's budget; flayr_total = nothing synced yet, amountMinor is the total flayr reserved against the caps (daily x days for a daily budget)."}}},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"identity":{"type":"object","nullable":true,"description":"FFE-1607: the TikTok identity (who the ad posts as) flayr sent at create. The network does not report it, so this is flayr's record; null when none was sent (the account default) or on other networks.","properties":{"id":{"type":"string"},"type":{"type":"string","nullable":true}}},"maxSpendMinor":{"type":"integer","nullable":true,"description":"The most this campaign can spend, in minor units (cents)."},"spendToDateMinor":{"type":"integer","nullable":true,"description":"From synced daily insights; null when none are synced."},"insightsToDate":{"type":"object","nullable":true,"description":"Delivery to date from the same synced rows as spendToDateMinor; null when none are synced.","properties":{"impressions":{"type":"integer"},"clicks":{"type":"integer"},"linkClicks":{"type":"integer","nullable":true},"leads":{"type":"integer","nullable":true},"conversions":{"type":"number","nullable":true},"days":{"type":"integer"},"syncedAt":{"type":"string","format":"date-time","nullable":true}}},"adSets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","nullable":true},"servingStatuses":{"type":"array","items":{"type":"string"},"description":"FFE-1607: the network's delivery reasons for the ad set, verbatim."},"provenance":{"type":"object","description":"Present when this row has import metadata.","required":["source","importedAt"],"properties":{"source":{"type":"string","enum":["sync","backfill","import"]},"importedAt":{"type":"number","description":"Import timestamp in Unix milliseconds."},"importBatchId":{"type":"string"},"sourceRef":{"type":"string","description":"Source API window or file and row reference."}}},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","nullable":true},"configuredStatus":{"type":"string","nullable":true,"description":"FFE-1607: the on/off switch flayr or the owner set (TikTok operation_status, e.g. DISABLE), apart from delivery `status`."},"servingStatuses":{"type":"array","items":{"type":"string"},"description":"FFE-1607: the network's own delivery reasons (TikTok secondary_status), verbatim; [] = none reported."},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"FFE-1607: the ad's schedule as the network reported it; null until synced or when none is set."},"endDate":{"type":"string","format":"date-time","nullable":true},"review":{"type":"object","properties":{"status":{"type":"string","enum":["rejected","in_review","approved","with_issues","unknown"]},"reason":{"type":"string","nullable":true},"message":{"type":"string","description":"Network reason when supplied; explicit unavailable explanation otherwise."},"source":{"type":"string"},"checkedAt":{"type":"string","format":"date-time","nullable":true,"description":"Last local sync, not a live review check."}}},"provenance":{"type":"object","description":"Present when this row has import metadata.","required":["source","importedAt"],"properties":{"source":{"type":"string","enum":["sync","backfill","import"]},"importedAt":{"type":"number","description":"Import timestamp in Unix milliseconds."},"importBatchId":{"type":"string"},"sourceRef":{"type":"string","description":"Source API window or file and row reference."}}},"headline":{"type":"string","nullable":true,"description":"Imported creative headline, or null when unreported."},"primaryText":{"type":"string","nullable":true,"description":"Imported creative body text, or null when unreported."},"button":{"type":"string","nullable":true,"description":"Imported creative call to action, or null when unreported."},"destinationUrl":{"type":"string","nullable":true,"description":"Imported creative destination URL, or null when unreported."},"thumbnailUrl":{"type":"string","nullable":true,"description":"Imported creative thumbnail URL, or null when unreported."},"page":{"type":"object","nullable":true,"description":"Meta only (FFE-1584): the Facebook Page the ad runs as, from the network ad's creative.pageId, read live on GET /api/v2/ads/campaigns/{id}. name and handle are set when it is one of the brand's connected Pages. null when not Meta, not reported, or the read failed; always null in the campaign list.","properties":{"pageId":{"type":"string","description":"The Meta Page id."},"name":{"type":"string","nullable":true},"handle":{"type":"string","nullable":true}}}}}}}}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}},"post":{"tags":["API v2"],"summary":"Create a paused ad campaign: Meta (Instant Form lead, click-to-message, website), TikTok, X, Google, LinkedIn, Reddit or Pinterest","security":[{"bearerAuth":[]}],"description":"goal lead_generation: a Meta lead campaign with one ad set (the Instant Form `leadGenFormId`, placements without Audience Network unless `placements` says otherwise, the age range and countries from `targeting`) and one image ad. goal messages (FFE-1342): a click-to-message ad whose conversations open in Messenger or Instagram Direct; its welcome message is the brand's automatic first reply (a greeting plus quick replies tagged with `armKey`), and each conversation lands as a lead with its ad/arm attribution. goal traffic or conversions (FFE-1537): a campaign that sends people to `targetUrl`, with one image ad, several image ads (`creatives`) or video ads; UTM parameters come from the owner's ads config, and Audience Network is never used. conversions optimizes for a pixel event (`promotedObject.customEventType`, default COMPLETE_REGISTRATION) on the brand's selected pixel, and is refused with 422 `PIXEL_NOT_PROVEN` unless the readiness check `pixel` passes (GET /api/v2/ads/readiness?objective=conversions). With `platform: tiktok` the same two goals create a TikTok video campaign on the brand's connected TikTok ad account (daily budget, `schedule.endDate` and `targeting.countries` required; 403 until an admin enables TikTok ad creation). With `platform: twitter` (or x) an X website-card campaign; with `platform: google | linkedin | reddit | pinterest` (FFE-1606) a paused standalone campaign on that network's connected ad account, from the same body and checks as the dashboard create (Google images are size-checked first; Reddit and Pinterest take budgetType daily or lifetime). Each network answers 403 `NETWORK_CREATE_DISABLED` until the owner switches its creation on. In every case everything is PAUSED and recorded as proposed: it never runs or spends until the owner approves it (Proposed campaigns, or POST /api/v2/ads/campaigns/{id}/approve). The budget goes through the owner's spend caps and the same checks as the dashboard create. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","goal","headline","body","budget"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"goal":{"type":"string","enum":["lead_generation","messages","traffic","conversions","engagement","awareness","video_views"],"description":"Meta: lead_generation (Instant Form), messages (click-to-message, Messenger + Instagram Direct), traffic (link clicks to targetUrl) or conversions (a pixel event on targetUrl). TikTok: traffic or conversions. twitter, google, linkedin, reddit, pinterest (FFE-1606): one of the goals the owner's ads config allows for that network (e.g. traffic, engagement, awareness, video_views)."},"targetUrl":{"type":"string","description":"traffic / conversions only, and required there: the page the ad sends people to (https on TikTok). On Meta the owner's UTM template is appended; TikTok can carry UTM parameters directly in targetUrl."},"destinationId":{"type":"string","description":"traffic / conversions: on an ad account under the landing destination registry, the registered destination to send people to; the registry then sets targetUrl."},"description":{"type":"string","description":"traffic / conversions on Meta: the line under the headline (link description)."},"creatives":{"type":"array","items":{"type":"object","properties":{"imageUrl":{"type":"string"},"imageMediaId":{"type":"string"},"creativeId":{"type":"string"},"headline":{"type":"string"},"body":{"type":"string"},"description":{"type":"string"},"linkUrl":{"type":"string"},"name":{"type":"string"}},"description":"Exactly one of imageUrl, imageMediaId or creativeId; copy left out is the campaign's own."},"description":"traffic / conversions on Meta: several image ads in one ad set, up to the ads create config cap. Instead of the single-creative fields, not with them."},"leadGenFormId":{"type":"string","description":"lead_generation only, and required there: an Instant Form id (GET /api/v2/ads/lead-forms)."},"armKey":{"type":"string","description":"messages only: the test arm in each quick-reply payload and lead (default: from the headline)."},"headline":{"type":"string","description":"Also the campaign name."},"body":{"type":"string","description":"The ad's primary text."},"imageUrl":{"type":"string","description":"The ad image, https on an allowed host: *.convex.cloud, img.clerk.com, ui-avatars.com, images.unsplash.com, *.googleusercontent.com, cdn.shopify.com, commerce.mdostal.com, shop.mdostal.com. For any other image, upload it and send imageMediaId. Send exactly one of imageUrl, imageMediaId, creativeId, video, videos."},"imageMediaId":{"type":"string","description":"lead_generation, traffic, conversions: a flayr upload (the storageId POST /api/v2/media/upload-url returns) instead of imageUrl."},"creativeId":{"type":"string","description":"lead_generation, traffic, conversions: a saved ad creative id instead of imageUrl. A website campaign uses its image only; the copy and link are this request's."},"video":{"type":"object","properties":{"mediaId":{"type":"string","description":"Meta: a flayr upload storageId."},"contentId":{"type":"string","description":"Meta: a Library item id."},"metaVideoId":{"type":"string","description":"Meta: a video already in the selected ad account."},"storageId":{"type":"string","description":"TikTok: a flayr upload storageId."},"libraryItemId":{"type":"string","description":"TikTok: a Library item id."},"name":{"type":"string","description":"The ad name; defaults to the headline, numbered for multiple ads."},"thumbnailUrl":{"type":"string","description":"An allowed-host image."}},"description":"Meta: exactly one of mediaId, contentId or metaVideoId. TikTok: exactly one of libraryItemId or storageId."},"videos":{"type":"array","items":{"type":"object","properties":{"mediaId":{"type":"string","description":"Meta: a flayr upload storageId."},"contentId":{"type":"string","description":"Meta: a Library item id."},"metaVideoId":{"type":"string","description":"Meta: a video already in the selected ad account."},"storageId":{"type":"string","description":"TikTok: a flayr upload storageId."},"libraryItemId":{"type":"string","description":"TikTok: a Library item id."},"name":{"type":"string","description":"The ad name; defaults to the headline, numbered for multiple ads."},"thumbnailUrl":{"type":"string","description":"An allowed-host image."}},"description":"Meta: exactly one of mediaId, contentId or metaVideoId. TikTok: exactly one of libraryItemId or storageId."},"description":"Several video ads in one ad set, up to the ads create config cap. Each is created PAUSED; a failed attachment is reported in ads and does not undo the campaign."},"aiDisclosure":{"type":"boolean","description":"Mark the video ads as AI-generated (set automatically for flayr AI videos). platform tiktok (FFE-1607): accepted and recorded, but the ad network API flayr creates through has no TikTok AI-generated-content field yet, so it is not applied: the response says aiDisclosure.applied false, and the owner must turn on TikTok's AI-generated content setting in TikTok Ads Manager before approving."},"savedTargetingId":{"type":"string","description":"lead_generation, traffic, conversions (Meta): a saved audience id (the id in the Ads > Audiences page URL). Its targeting is the base; fields in `targeting` override it."},"includeAudienceIds":{"type":"array","items":{"type":"string"},"description":"FFE-1602, Meta lead_generation, traffic, conversions: flayr audience ids (GET /api/v2/ads/audiences) the ad set targets, up to the owner's limit (400 AUDIENCE_LIMIT)."},"excludeAudienceIds":{"type":"array","items":{"type":"string"},"description":"FFE-1602, Meta lead_generation, traffic, conversions: flayr audience ids the ad set excludes (e.g. existing customers). An id may not be both included and excluded."},"budget":{"type":"number","description":"In dollars (account currency). Above the owner's spend caps or the account limit the create is refused (400). platform tiktok, twitter, google, linkedin: dollars per day (the whole run, per day x days, is reserved against the caps). reddit, pinterest: per day, or the whole run with budgetType lifetime."},"budgetType":{"type":"string","enum":["daily","lifetime"],"description":"Default lifetime on Meta. platform tiktok, twitter, google, linkedin: daily only. reddit, pinterest: daily or lifetime."},"schedule":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}},"description":"ISO dates; default now to +7 days. platform tiktok, twitter, google, linkedin, reddit, pinterest: endDate is required."},"targeting":{"type":"object","properties":{"ageMin":{"type":"integer"},"ageMax":{"type":"integer"},"countries":{"type":"array","items":{"type":"string"}},"genders":{"type":"array","items":{"type":"string"}},"interests":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}]},"description":"Meta: interest id strings (GET /api/v2/ads/targeting/search). TikTok (FFE-1607): { id, name } objects from GET /api/v2/ads/targeting/search?platform=tiktok; interest category ids as returned, interestKeyword ids as `keyword:<id>`."},"ageGroups":{"type":"array","items":{"type":"string","enum":["18-24","25-34","35-44","45-54","55+"]},"description":"TikTok only (FFE-1607): TikTok's age buckets, instead of ageMin/ageMax. TikTok has no free age range; ageMin/ageMax must fall on these bucket edges (ageMax 65 or 100 = 55+)."},"gender":{"type":"string","enum":["all","male","female"],"description":"TikTok and Pinterest; default all."},"behaviors":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"description":"TikTok only (FFE-1607): behavior ids and hashtag ids (`hashtag:<id>`) from GET /api/v2/ads/targeting/search?platform=tiktok."}},"description":"Age range 13-65 and the usual targeting fields. tiktok: countries (required), age on TikTok's buckets (ageGroups or ageMin/ageMax on bucket edges), gender, interests and behaviors. reddit also takes communities (e.g. r/Portland) and conversationKeywords; pinterest gender and languages; the fields each network reads are the dashboard create's."},"placements":{"oneOf":[{"type":"string","enum":["automatic","facebook_instagram","facebook","instagram","feeds","reels","stories"]},{"type":"object","properties":{"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram"]}},"surfaces":{"type":"array","items":{"type":"string","enum":["feeds","reels","stories"]}}}}],"description":"Default automatic = Facebook, Instagram and Messenger. Audience Network is never used. feeds/reels/stories (or { surfaces }) pick those positions on Facebook and Instagram."},"callToAction":{"type":"string","description":"A CTA from the ads create config (default: the owner's default, e.g. LEARN_MORE; SIGN_UP suits a lead form)."},"promotedObject":{"type":"object","properties":{"pageId":{"type":"string"},"customEventType":{"type":"string"},"pixelId":{"type":"string"}},"description":"lead_generation: pageId, the Facebook Page the lead ad runs from. conversions: customEventType, the pixel event to optimize for (Meta defaults to COMPLETE_REGISTRATION; TikTok accepts its optimization event, e.g. ON_WEB_REGISTER), and optionally pixelId, which on Meta must be the brand's selected pixel and on TikTok is required. Not accepted with traffic on Meta."},"optimizationGoal":{"type":"string","enum":["link_clicks","landing_page_views","complete_registration","start_trial","paid_conversion"],"description":"FFE-1600, Meta traffic / conversions: what the ad set optimises for. link_clicks and landing_page_views belong to goal traffic; complete_registration, start_trial and paid_conversion (the owner's paid event, Purchase or Subscribe) to goal conversions on the brand's pixel. Not sent with promotedObject.customEventType. The allowed goals are the owner's ads config (400 OPTIMISATION_GOAL_NOT_ALLOWED)."},"bidStrategy":{"type":"string","enum":["highest_volume","cost_per_result","bid_cap"],"description":"FFE-1600, Meta traffic / conversions: highest_volume (most results for the budget, Meta's default), cost_per_result (an average cost-per-result goal) or bid_cap (a hard cap per auction). Allowed strategies are the owner's ads config (400 BID_STRATEGY_NOT_ALLOWED)."},"costPerResultGoal":{"type":"number","description":"FFE-1600: dollars per result for cost_per_result or bid_cap (required with them; alone it means cost_per_result). Must be inside the owner's configured range (400 COST_PER_RESULT_OUT_OF_RANGE)."},"platform":{"type":"string","enum":["facebook","instagram","tiktok","twitter","x","google","linkedin","reddit","pinterest"],"description":"Default facebook. tiktok (traffic / conversions only) creates a TikTok video campaign on the brand's connected TikTok ad account. twitter (or x) creates an X website-card campaign; google, linkedin, reddit and pinterest create a paused standalone campaign with that network's dashboard create body (FFE-1606). Each answers 403 NETWORK_CREATE_DISABLED until the owner switches that network's creation on (GET /api/v2/ads/readiness networkSwitches). openai answers 400 PLATFORM_NOT_SUPPORTED."},"google":{"type":"object","description":"platform google only, and required there: { campaignType (demand_gen, search, display, pmax as the config allows), businessName, headlines, longHeadlines, descriptions, images { landscape, square, portrait, logo, ... } (https on an allowed host; every image is size-checked before anything is created), youtubeVideoIds, keywords, negativeKeywords, channels }, as the dashboard Google create."},"boardId":{"type":"string","description":"platform pinterest only, optional: the Pinterest board the ad Pin is created on."},"carouselCards":{"type":"array","items":{"type":"object"},"description":"platform reddit only: carousel cards instead of imageUrl, as the dashboard Reddit create."},"adAccountId":{"type":"string","description":"Default: the brand's selected ad account; must match it."},"identityId":{"type":"string","description":"TikTok identity id; optional."},"identityType":{"type":"string","enum":["TT_USER","CUSTOMIZED_USER","BC_AUTH_TT"],"description":"TikTok only."},"smartPlus":{"type":"boolean","description":"TikTok only, opt-in after admin enablement; requires conversions with a pixel and event."},"specialAdCategories":{"type":"array","items":{"type":"string"}},"idempotencyKey":{"type":"string","description":"Optional; repeats with the same key return the first result instead of creating twice."}}}}}},"responses":{"200":{"description":"Paused campaign created, or an idempotent replay","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","description":"Flayr campaign id; use it with campaign read-back, approve and pause."},"platformCampaignId":{"type":"string","nullable":true,"description":"The ad network campaign id, when returned; website campaigns."},"zernioCampaignId":{"type":"string"},"goal":{"type":"string","enum":["traffic","conversions"],"description":"Returned for website campaigns."},"status":{"type":"string","description":"Campaign delivery status: PAUSED for website creation."},"persisted":{"type":"boolean"},"approvalStatus":{"type":"string","enum":["proposed"]},"actionId":{"type":"string"},"replayed":{"type":"boolean"},"ads":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string"}}}},"targeting":{"type":"object","description":"TikTok (FFE-1607): the targeting flayr sent, after normalization (countries, ageGroups, gender, interests, behaviors)."},"linkUrl":{"type":"string","nullable":true,"description":"TikTok (FFE-1607): the landing URL the ad was created with, including the UTM parameters from the owner's ads config."},"utm":{"type":"object","description":"TikTok (FFE-1607): the owner's UTM template as applied to linkUrl.","properties":{"applied":{"type":"boolean","description":"False when UTM is off in the ads config or the template had no usable tags."},"tags":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"description":"The parameters appended; Meta macros in the template are mapped to TikTok's (`__UPPER__`), kept literal in the URL."},"dropped":{"type":"array","items":{"type":"string"},"description":"Keys of template parameters left out because they use a macro TikTok has no equivalent for."}}},"schedule":{"type":"object","description":"TikTok (FFE-1607): the schedule sent to the network.","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"identity":{"type":"object","description":"TikTok (FFE-1607): the identity the ad posts as, when identityId was sent. Absent = the ad account's default identity.","properties":{"id":{"type":"string"},"type":{"type":"string","nullable":true}}},"sync":{"type":"object","description":"TikTok (FFE-1607): whether flayr asked the ad network for the campaign tree right away, so GET /api/v2/ads/campaigns/{id} fills in ad sets, objective and budget within a couple of minutes instead of at the next hourly sync. A failed request never fails the create.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string","description":"When requested is false: not_found, no_selection, account_mismatch, not_scheduled or error."}}},"aiDisclosure":{"type":"object","description":"TikTok, when aiDisclosure was sent (FFE-1607).","properties":{"requested":{"type":"boolean"},"applied":{"type":"boolean","enum":[false]},"reason":{"type":"string","description":"Why it could not be applied and what the owner must do in TikTok Ads Manager."}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"422":{"description":"conversions only: the pixel does not pass the readiness check `pixel`; nothing was created","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["PIXEL_NOT_PROVEN"]},"readinessCheck":{"type":"object","properties":{"id":{"type":"string","enum":["pixel"]},"state":{"type":"string"},"detail":{"type":"string"},"fixUrl":{"type":"string"}}},"readiness":{"type":"string","description":"The readiness read that shows the check."}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/campaigns/{id}":{"get":{"tags":["API v2"],"summary":"Get an ad campaign","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string","description":"Flayr campaign id (the one pause/stop take)."},"provenance":{"type":"object","description":"Present when this row has import metadata.","required":["source","importedAt"],"properties":{"source":{"type":"string","enum":["sync","backfill","import"]},"importedAt":{"type":"number","description":"Import timestamp in Unix milliseconds."},"importBatchId":{"type":"string"},"sourceRef":{"type":"string","description":"Source API window or file and row reference."}}},"platform":{"type":"string"},"platformCampaignId":{"type":"string","nullable":true,"description":"The ad network's own campaign id, when known."},"name":{"type":"string"},"status":{"type":"string","description":"The vendor's normalized status. It can read error for network states that are not failures; read platformStatus for the real state."},"platformStatus":{"type":"string","nullable":true,"description":"FFE-1607: the network's raw campaign status (TikTok secondary_status such as CAMPAIGN_STATUS_NOT_START); null when the network sent none."},"sync":{"type":"object","description":"FFE-1607: whether status and the ad sets come from the network yet. never = only flayr's create record exists (status is the PAUSED hold flayr asked for, adSets are empty until the first sync).","properties":{"state":{"type":"string","enum":["synced","never"]},"lastSeenAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"objective":{"type":"string","nullable":true},"budget":{"type":"object","properties":{"type":{"type":"string","enum":["daily","lifetime"],"nullable":true},"amountMinor":{"type":"integer","nullable":true},"currency":{"type":"string","nullable":true},"source":{"type":"string","enum":["network","flayr_total"],"nullable":true,"description":"FFE-1607: network = the network's budget; flayr_total = nothing synced yet, amountMinor is the total flayr reserved against the caps (daily x days for a daily budget)."}}},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"identity":{"type":"object","nullable":true,"description":"FFE-1607: the TikTok identity (who the ad posts as) flayr sent at create. The network does not report it, so this is flayr's record; null when none was sent (the account default) or on other networks.","properties":{"id":{"type":"string"},"type":{"type":"string","nullable":true}}},"maxSpendMinor":{"type":"integer","nullable":true,"description":"The most this campaign can spend, in minor units (cents)."},"spendToDateMinor":{"type":"integer","nullable":true,"description":"From synced daily insights; null when none are synced."},"insightsToDate":{"type":"object","nullable":true,"description":"Delivery to date from the same synced rows as spendToDateMinor; null when none are synced.","properties":{"impressions":{"type":"integer"},"clicks":{"type":"integer"},"linkClicks":{"type":"integer","nullable":true},"leads":{"type":"integer","nullable":true},"conversions":{"type":"number","nullable":true},"days":{"type":"integer"},"syncedAt":{"type":"string","format":"date-time","nullable":true}}},"adSets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","nullable":true},"servingStatuses":{"type":"array","items":{"type":"string"},"description":"FFE-1607: the network's delivery reasons for the ad set, verbatim."},"provenance":{"type":"object","description":"Present when this row has import metadata.","required":["source","importedAt"],"properties":{"source":{"type":"string","enum":["sync","backfill","import"]},"importedAt":{"type":"number","description":"Import timestamp in Unix milliseconds."},"importBatchId":{"type":"string"},"sourceRef":{"type":"string","description":"Source API window or file and row reference."}}},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","nullable":true},"configuredStatus":{"type":"string","nullable":true,"description":"FFE-1607: the on/off switch flayr or the owner set (TikTok operation_status, e.g. DISABLE), apart from delivery `status`."},"servingStatuses":{"type":"array","items":{"type":"string"},"description":"FFE-1607: the network's own delivery reasons (TikTok secondary_status), verbatim; [] = none reported."},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"FFE-1607: the ad's schedule as the network reported it; null until synced or when none is set."},"endDate":{"type":"string","format":"date-time","nullable":true},"review":{"type":"object","properties":{"status":{"type":"string","enum":["rejected","in_review","approved","with_issues","unknown"]},"reason":{"type":"string","nullable":true},"message":{"type":"string","description":"Network reason when supplied; explicit unavailable explanation otherwise."},"source":{"type":"string"},"checkedAt":{"type":"string","format":"date-time","nullable":true,"description":"Last local sync, not a live review check."}}},"provenance":{"type":"object","description":"Present when this row has import metadata.","required":["source","importedAt"],"properties":{"source":{"type":"string","enum":["sync","backfill","import"]},"importedAt":{"type":"number","description":"Import timestamp in Unix milliseconds."},"importBatchId":{"type":"string"},"sourceRef":{"type":"string","description":"Source API window or file and row reference."}}},"headline":{"type":"string","nullable":true,"description":"Imported creative headline, or null when unreported."},"primaryText":{"type":"string","nullable":true,"description":"Imported creative body text, or null when unreported."},"button":{"type":"string","nullable":true,"description":"Imported creative call to action, or null when unreported."},"destinationUrl":{"type":"string","nullable":true,"description":"Imported creative destination URL, or null when unreported."},"thumbnailUrl":{"type":"string","nullable":true,"description":"Imported creative thumbnail URL, or null when unreported."},"page":{"type":"object","nullable":true,"description":"Meta only (FFE-1584): the Facebook Page the ad runs as, from the network ad's creative.pageId, read live on GET /api/v2/ads/campaigns/{id}. name and handle are set when it is one of the brand's connected Pages. null when not Meta, not reported, or the read failed; always null in the campaign list.","properties":{"pageId":{"type":"string","description":"The Meta Page id."},"name":{"type":"string","nullable":true},"handle":{"type":"string","nullable":true}}}}}}}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Campaign not found in this brand"}}},"delete":{"tags":["API v2"],"summary":"Delete an ad campaign","description":"Deletes the campaign in Flayr and on the ad network, through the same write as the Flayr app. Needs a key with the explicit ads:manage scope (write alone is not enough). A running campaign, or one that spent today, answers 409 unless stopFirst=true, which pauses it first. A campaign another change is in progress on answers 409. Deleting cannot be undone; to stop spending but keep the campaign, pause it instead.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."},{"name":"stopFirst","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Pause a running campaign first, then delete it."},{"name":"idempotencyKey","in":"query","required":false,"schema":{"type":"string"},"description":"Retrying with the same key never runs the delete twice. Also accepted as the Idempotency-Key header or in the body."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted, with the Flayr and ad network read-backs","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"status":{"type":"string","enum":["deleted"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"flayr":{"type":"string","enum":["deleted","still_present"],"description":"Read-back: the campaign no longer reads in Flayr."},"network":{"type":"string","enum":["deleted","still_present","unknown"],"description":"Read-back on the ad network; unknown when that read failed."},"stoppedFirst":{"type":"boolean","description":"true when stopFirst paused a running campaign before the delete."},"code":{"type":"string","description":"On a refusal: CAMPAIGN_RUNNING, CAMPAIGN_SPENT_RECENTLY or STOP_FAILED."},"lastSpendDate":{"type":"string","description":"On CAMPAIGN_SPENT_RECENTLY: the latest day with spend (YYYY-MM-DD)."},"error":{"type":"string"}}}}}},"400":{"description":"Invalid body, idempotency key or stopFirst"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key without ads:manage, ads not available, or another brand for a brand-bound key"},"404":{"description":"Campaign not found in this brand"},"409":{"description":"Running or spent recently (pass stopFirst=true), or another change is in progress","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"status":{"type":"string","enum":["deleted"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"flayr":{"type":"string","enum":["deleted","still_present"],"description":"Read-back: the campaign no longer reads in Flayr."},"network":{"type":"string","enum":["deleted","still_present","unknown"],"description":"Read-back on the ad network; unknown when that read failed."},"stoppedFirst":{"type":"boolean","description":"true when stopFirst paused a running campaign before the delete."},"code":{"type":"string","description":"On a refusal: CAMPAIGN_RUNNING, CAMPAIGN_SPENT_RECENTLY or STOP_FAILED."},"lastSpendDate":{"type":"string","description":"On CAMPAIGN_SPENT_RECENTLY: the latest day with spend (YYYY-MM-DD)."},"error":{"type":"string"}}}}}},"422":{"description":"Idempotency key already used for a different request","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"status":{"type":"string","enum":["deleted"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"flayr":{"type":"string","enum":["deleted","still_present"],"description":"Read-back: the campaign no longer reads in Flayr."},"network":{"type":"string","enum":["deleted","still_present","unknown"],"description":"Read-back on the ad network; unknown when that read failed."},"stoppedFirst":{"type":"boolean","description":"true when stopFirst paused a running campaign before the delete."},"code":{"type":"string","description":"On a refusal: CAMPAIGN_RUNNING, CAMPAIGN_SPENT_RECENTLY or STOP_FAILED."},"lastSpendDate":{"type":"string","description":"On CAMPAIGN_SPENT_RECENTLY: the latest day with spend (YYYY-MM-DD)."},"error":{"type":"string"}}}}}},"502":{"description":"The ad network refused or failed","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"status":{"type":"string","enum":["deleted"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"flayr":{"type":"string","enum":["deleted","still_present"],"description":"Read-back: the campaign no longer reads in Flayr."},"network":{"type":"string","enum":["deleted","still_present","unknown"],"description":"Read-back on the ad network; unknown when that read failed."},"stoppedFirst":{"type":"boolean","description":"true when stopFirst paused a running campaign before the delete."},"code":{"type":"string","description":"On a refusal: CAMPAIGN_RUNNING, CAMPAIGN_SPENT_RECENTLY or STOP_FAILED."},"lastSpendDate":{"type":"string","description":"On CAMPAIGN_SPENT_RECENTLY: the latest day with spend (YYYY-MM-DD)."},"error":{"type":"string"}}}}}}}}},"/api/v2/ads/campaigns/{id}/pause":{"post":{"tags":["API v2"],"summary":"Pause an ad campaign","description":"Pauses the campaign on the ad network (it stops spending). Needs a key with the write scope. There is no resume or activate through the API: a campaign is turned back on in the Flayr app by a brand owner or admin.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["pause","stop"],"default":"pause","description":"stop = a pause you mean as final; the network shows paused either way."},"idempotencyKey":{"type":"string","description":"Retrying with the same key never runs the change twice."}}}}}},"responses":{"200":{"description":"Paused","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"action":{"type":"string","enum":["pause","stop"]},"status":{"type":"string","enum":["paused"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"error":{"type":"string","description":"Only on failure."},"code":{"type":"string","description":"Only on some failures."},"retryAfterMs":{"type":"integer","description":"Only on some failures."}}}}}},"400":{"description":"Invalid body"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Read-only key, ads not available, or another brand for a brand-bound key"},"404":{"description":"Campaign not found in this brand"},"409":{"description":"Another change to this campaign is in progress","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"action":{"type":"string","enum":["pause","stop"]},"status":{"type":"string","enum":["paused"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"error":{"type":"string","description":"Only on failure."},"code":{"type":"string","description":"Only on some failures."},"retryAfterMs":{"type":"integer","description":"Only on some failures."}}}}}},"502":{"description":"The ad network refused or failed","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"action":{"type":"string","enum":["pause","stop"]},"status":{"type":"string","enum":["paused"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"error":{"type":"string","description":"Only on failure."},"code":{"type":"string","description":"Only on some failures."},"retryAfterMs":{"type":"integer","description":"Only on some failures."}}}}}}}}},"/api/v2/ads/campaigns/{id}/stop":{"post":{"tags":["API v2"],"summary":"Stop an ad campaign","description":"Stops the campaign on the ad network (it stops spending). Needs a key with the write scope. There is no resume or activate through the API: a campaign is turned back on in the Flayr app by a brand owner or admin.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"type":"string","description":"Retrying with the same key never runs the change twice."}}}}}},"responses":{"200":{"description":"Paused","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"action":{"type":"string","enum":["pause","stop"]},"status":{"type":"string","enum":["paused"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"error":{"type":"string","description":"Only on failure."},"code":{"type":"string","description":"Only on some failures."},"retryAfterMs":{"type":"integer","description":"Only on some failures."}}}}}},"400":{"description":"Invalid body"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Read-only key, ads not available, or another brand for a brand-bound key"},"404":{"description":"Campaign not found in this brand"},"409":{"description":"Another change to this campaign is in progress","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"action":{"type":"string","enum":["pause","stop"]},"status":{"type":"string","enum":["paused"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"error":{"type":"string","description":"Only on failure."},"code":{"type":"string","description":"Only on some failures."},"retryAfterMs":{"type":"integer","description":"Only on some failures."}}}}}},"502":{"description":"The ad network refused or failed","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"action":{"type":"string","enum":["pause","stop"]},"status":{"type":"string","enum":["paused"]},"outcome":{"type":"string","nullable":true},"operationId":{"type":"string","nullable":true},"error":{"type":"string","description":"Only on failure."},"code":{"type":"string","description":"Only on some failures."},"retryAfterMs":{"type":"integer","description":"Only on some failures."}}}}}}}}},"/api/v2/ads/snapshots":{"get":{"tags":["API v2"],"summary":"Read saved ads snapshots","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."},{"name":"id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Snapshot or recent snapshot headers","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}},"post":{"tags":["API v2"],"summary":"Collect an immutable ads data snapshot","security":[{"bearerAuth":[]}],"description":"Read-only vendor collection. Saves facts; no analysis, charge, ad edits or activation.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromDate","toDate","adAccountIds"],"properties":{"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"},"adAccountIds":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Snapshot id","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}}},"/api/v2/ads/insights":{"get":{"tags":["API v2"],"summary":"Ad insights","security":[{"bearerAuth":[]}],"description":"Synced daily results summed per campaign (`level=campaign`, default) or per ad (`level=ad`, each ad with the Library `contentId` it was built from, null when unlinked), with totals per currency. At most 93 days.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"YYYY-MM-DD; default 30 days ago"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"YYYY-MM-DD; default today"},{"name":"level","in":"query","required":false,"schema":{"type":"string","enum":["campaign","ad"],"default":"campaign"}}],"responses":{"200":{"description":"Insights","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"from":{"type":"string","description":"YYYY-MM-DD"},"to":{"type":"string","description":"YYYY-MM-DD"},"level":{"type":"string","enum":["campaign","ad"]},"unlinked":{"type":"object","description":"level=ad only: ads with no Library content link.","properties":{"ads":{"type":"integer"},"spend":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"spendMinor":{"type":"integer"}}}}}},"syncedAt":{"type":"string","format":"date-time","nullable":true,"description":"Last successful insights sync for the selected ad accounts; null = never synced."},"lastCheckedAt":{"type":"string","format":"date-time","nullable":true,"description":"Last sync attempt, successful or not."},"stale":{"type":"boolean","description":"True when no sync succeeded within two sync windows: an empty `rows` then means \"not synced\", not \"no spend\"."},"syncCadenceMinutes":{"type":"integer","nullable":true,"description":"Insights sync once per this many minutes."},"accounts":{"type":"array","description":"Spend each selected ad account recorded in the range, across every brand that shares it.","items":{"type":"object","properties":{"platformAdAccountId":{"type":"string"},"platform":{"type":"string"},"currency":{"type":"string"},"spendMinor":{"type":"integer"},"campaigns":{"type":"integer"}}}},"totals":{"type":"array","description":"One row per currency.","items":{"type":"object","properties":{"currency":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"spendMinor":{"type":"integer"}}}},"rows":{"type":"array","items":{"type":"object","properties":{"campaignId":{"type":"string","nullable":true},"platformCampaignId":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"platform":{"type":"string","nullable":true},"currency":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"spendMinor":{"type":"integer"},"linkClicks":{"type":"integer","nullable":true},"leads":{"type":"integer","nullable":true},"days":{"type":"integer"},"importedDays":{"type":"integer","description":"How many of `days` came from a stats file import (POST /api/v2/ads/imports/files), not the sync. 0 = all synced."},"adId":{"type":"string","nullable":true},"platformAdId":{"type":"string","nullable":true},"contentId":{"type":"string","nullable":true},"campaignName":{"type":"string","nullable":true},"ctr":{"type":"number","nullable":true,"description":"Percent."},"videoViews":{"type":"integer","nullable":true},"thruplays":{"type":"integer","nullable":true},"conversions":{"type":"number","nullable":true}}}}}}}}},"400":{"description":"Invalid range or level"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"}}}},"/api/v2/ads/readiness":{"get":{"tags":["API v2"],"summary":"Ads readiness","security":[{"bearerAuth":[]}],"description":"Whether each connected network and ad account can run ads, and what to fix. Pass `objective` to get the verdict for one campaign objective: each check is marked `blocks` or `advisory` for it and `overall` counts only the blocking ones (for `lead_generation`, the Page, Lead Ads Terms and Instant Form privacy URL block; the pixel is advisory).","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand. A brand-bound key is always pinned to its brand; any other value is 403."},{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Request fresh network reads. Reuses results younger than 30 seconds to protect the platform; inspect checkedAt."},{"name":"objective","in":"query","required":false,"schema":{"type":"string","enum":["engagement","traffic","awareness","video_views","lead_generation","lead_conversion","conversions","app_promotion","catalog_sales","job_applicants"]},"description":"The campaign objective to check readiness for. Omit for the every-objective verdict, where the pixel, domain and business verification all block."}],"responses":{"200":{"description":"Readiness","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","nullable":true},"objective":{"type":"string","nullable":true,"description":"The campaign objective every `overall` and `gate` is for; null when none was requested."},"checkedAt":{"type":"string","format":"date-time"},"networks":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"label":{"type":"string"},"overall":{"type":"string","enum":["ready","needs_action","pending","check","not_connected"],"nullable":true},"setup":{"type":"array","description":"Steps to run ads here: connect, ad_account, funding, pixel, claim_offer. `state` is done, missing or check (flayr cannot read it; confirm on the platform). `url` is the platform page, null when none.","items":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["done","missing","check"]},"label":{"type":"string"},"detail":{"type":"string"},"url":{"type":"string","nullable":true}}}},"missingSteps":{"type":"integer","description":"How many `setup` steps are `missing`."},"offer":{"type":"object","nullable":true,"description":"The active new-advertiser offer for this network (terms as GET /api/v2/ads/offers lists them); null when none."},"offerClaimStatus":{"type":"string","nullable":true,"description":"The brand's furthest claim for that offer (not_claimed, claimed, earned, expired, ineligible); null when not read or no brand."},"connections":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string","nullable":true},"overall":{"type":"string","enum":["ready","needs_action","pending","check","not_connected"],"nullable":true},"reconnect":{"type":"boolean"},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string"},"detail":{"type":"string"},"fixUrl":{"type":"string","nullable":true},"gate":{"type":"string","nullable":true,"description":"`blocks` or `advisory`. `blocks`: this check counts toward `overall` for the requested objective. `advisory`: reported, but a campaign with that objective launches without it. A `manual` check never moves `overall`; when it `blocks`, confirm it on the platform before launching."}}}},"adAccountsNotShown":{"type":"integer"},"adAccounts":{"type":"array","items":{"type":"object","properties":{"platformAdAccountId":{"type":"string"},"name":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"overall":{"type":"string","enum":["ready","needs_action","pending","check","not_connected"],"nullable":true},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string"},"detail":{"type":"string"},"fixUrl":{"type":"string","nullable":true},"gate":{"type":"string","nullable":true,"description":"`blocks` or `advisory`. `blocks`: this check counts toward `overall` for the requested objective. `advisory`: reported, but a campaign with that objective launches without it. A `manual` check never moves `overall`; when it `blocks`, confirm it on the platform before launching."}}}},"pixels":{"type":"array","items":{"type":"object","description":"One pixel (dataset) the ad network lists for the ad account, and what the `pixel` check made of it.","properties":{"pixelId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"`active` or `inactive`."},"lastFiredAt":{"type":"string","format":"date-time","nullable":true,"description":"The last event the network reports for the pixel; null when it reports none."},"recentEvents":{"type":"integer","nullable":true,"description":"Meta only: events counted in the pixel freshness window, read when no last-fired time is reported. null when not read or not readable."},"recentEventNames":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"count":{"type":"integer"}}}},"owner":{"type":"string","description":"`this_ad_account`, `another_ad_account` or `not_reported`."},"sharedWithThisAdAccount":{"type":"boolean","nullable":true,"description":"For a pixel another ad account owns: whether it is shared with this one. null when not read."},"counted":{"type":"boolean","description":"Whether the `pixel` check counted this pixel for the ad account. A pixel another ad account owns counts only when it is shared with this one."}}}}}}}}}}}}}}}}}},"400":{"description":"Unknown objective"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand"},"502":{"description":"The ad network could not be reached"}}}},"/api/v2/campaigns/{id}/review":{"get":{"tags":["API v2"],"summary":"Get a campaign's review sections","description":"The campaign's pieces grouped into review sections (by episode, week, channel set, variant group, or the creator's own), each piece with preview URLs, caption, labels, bookings and QA, and each section with its previous rounds' fix notes. Needs `read`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id.","schema":{"type":"string"}},{"name":"sectionId","in":"query","required":false,"schema":{"type":"string"},"description":"Only this section."},{"name":"pieces","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"false = sections and counts only."}],"responses":{"200":{"description":"Review page","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"timezone":{"type":"string","nullable":true},"brandId":{"type":"string"},"reviewUrl":{"type":"string"}}},"approvalMode":{"type":"string","enum":["off","optional","required"],"description":"The brand's review mode. optional never blocks posting."},"canDecide":{"type":"boolean"},"unsectionedCount":{"type":"integer","description":"Pieces not in a section yet: POST this path to group them."},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["week","channel_set","variant_group","episode","phase","custom"]},"source":{"type":"string","enum":["inferred","creator"]},"status":{"type":"string","enum":["pending","fixing","approved","dropped"]},"round":{"type":"integer","description":"Starts at 1; each \"send back to fix\" opens the next round."},"pendingSince":{"type":"string","format":"date-time","nullable":true},"escalated":{"type":"boolean","description":"Waiting longer than the brand's escalation window (default 24 h)."},"fixNotes":{"type":"array","description":"Every previous round's fix note, oldest first.","items":{"type":"object","properties":{"round":{"type":"integer"},"note":{"type":"string"},"at":{"type":"string","format":"date-time","nullable":true}}}},"counts":{"type":"object","properties":{"pending":{"type":"integer"},"approved":{"type":"integer"},"fix":{"type":"integer"},"dropped":{"type":"integer"},"qaFailed":{"type":"integer"}}},"reviewUrl":{"type":"string","description":"This section on the campaign review page in flayr."},"pieces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Piece id (pass in pieceIds)."},"contentId":{"type":"string"},"state":{"type":"string","enum":["pending","approved","fix","dropped"]},"round":{"type":"integer"},"note":{"type":"string","nullable":true,"description":"The fix note of its last decision."},"error":{"type":"string","nullable":true,"description":"Why the last decision failed for this piece (e.g. the platform refused to unschedule)."},"pendingSince":{"type":"string","format":"date-time","nullable":true},"preview":{"type":"object","properties":{"kind":{"type":"string","enum":["video","image","audio","text"]},"videoUrl":{"type":"string","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"posterUrl":{"type":"string","nullable":true},"audioUrl":{"type":"string","nullable":true}}},"caption":{"type":"string"},"platformText":{"type":"object","additionalProperties":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"bookings":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"review":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"canApprove":{"type":"boolean"}}}}}},"qa":{"type":"object","description":"QA gate run before a piece is surfaced or auto-booked: silence/loudness on video, transcript, captions, links. \"fail\" blocks approve unless overrideQa.","properties":{"status":{"type":"string","enum":["pass","warn","fail"]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["silence","transcript","caption","links","placeholder","product"]},"status":{"type":"string","enum":["pass","warn","fail","unknown"]},"detail":{"type":"string"}}}}}}}}}}}}}}}}},"404":{"description":"Not found (or another brand, for a brand-bound key)"}}},"post":{"tags":["API v2"],"summary":"Group a campaign into review sections","description":"Puts the campaign's not-yet-sectioned pieces into sections, inferred by `groupBy` (default: the brand's setting). Existing sections and decisions are kept. Needs `publish` or `review`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"groupBy":{"type":"string","enum":["week","channel_set","variant_group","episode","phase"]}}}}}},"responses":{"200":{"description":"Review page, plus `added`","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"timezone":{"type":"string","nullable":true},"brandId":{"type":"string"},"reviewUrl":{"type":"string"}}},"approvalMode":{"type":"string","enum":["off","optional","required"],"description":"The brand's review mode. optional never blocks posting."},"canDecide":{"type":"boolean"},"unsectionedCount":{"type":"integer","description":"Pieces not in a section yet: POST this path to group them."},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["week","channel_set","variant_group","episode","phase","custom"]},"source":{"type":"string","enum":["inferred","creator"]},"status":{"type":"string","enum":["pending","fixing","approved","dropped"]},"round":{"type":"integer","description":"Starts at 1; each \"send back to fix\" opens the next round."},"pendingSince":{"type":"string","format":"date-time","nullable":true},"escalated":{"type":"boolean","description":"Waiting longer than the brand's escalation window (default 24 h)."},"fixNotes":{"type":"array","description":"Every previous round's fix note, oldest first.","items":{"type":"object","properties":{"round":{"type":"integer"},"note":{"type":"string"},"at":{"type":"string","format":"date-time","nullable":true}}}},"counts":{"type":"object","properties":{"pending":{"type":"integer"},"approved":{"type":"integer"},"fix":{"type":"integer"},"dropped":{"type":"integer"},"qaFailed":{"type":"integer"}}},"reviewUrl":{"type":"string","description":"This section on the campaign review page in flayr."},"pieces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Piece id (pass in pieceIds)."},"contentId":{"type":"string"},"state":{"type":"string","enum":["pending","approved","fix","dropped"]},"round":{"type":"integer"},"note":{"type":"string","nullable":true,"description":"The fix note of its last decision."},"error":{"type":"string","nullable":true,"description":"Why the last decision failed for this piece (e.g. the platform refused to unschedule)."},"pendingSince":{"type":"string","format":"date-time","nullable":true},"preview":{"type":"object","properties":{"kind":{"type":"string","enum":["video","image","audio","text"]},"videoUrl":{"type":"string","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"posterUrl":{"type":"string","nullable":true},"audioUrl":{"type":"string","nullable":true}}},"caption":{"type":"string"},"platformText":{"type":"object","additionalProperties":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"bookings":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"review":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"canApprove":{"type":"boolean"}}}}}},"qa":{"type":"object","description":"QA gate run before a piece is surfaced or auto-booked: silence/loudness on video, transcript, captions, links. \"fail\" blocks approve unless overrideQa.","properties":{"status":{"type":"string","enum":["pass","warn","fail"]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["silence","transcript","caption","links","placeholder","product"]},"status":{"type":"string","enum":["pass","warn","fail","unknown"]},"detail":{"type":"string"}}}}}}}}}}}}}}}}},"403":{"description":"Viewer role or missing scope"},"404":{"description":"Not found"},"422":{"description":"Bad groupBy"}}}},"/api/v2/campaigns/{id}/review/sections/{sectionId}":{"post":{"tags":["API v2"],"summary":"Approve, fix or drop a review section","description":"approve: approves all pending pieces (or `pieceIds`) — their held posts GO LIVE at their slots; needs the explicit `review` scope; QA-failed pieces are skipped unless overrideQa. fix: send back to fix with a `note` — holds the bookings and opens a new round of this section only; other sections keep their state and bookings. drop: holds the bookings and drops the pieces. ready: fixed pieces go back to pending review. fix/drop/ready need `review` or `publish`. Agency plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id.","schema":{"type":"string"}},{"name":"sectionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["approve","fix","drop","ready"]},"pieceIds":{"type":"array","maxItems":500,"items":{"type":"string"},"description":"Only these pieces (\"approve selected\"). Default: every eligible piece in the section."},"note":{"type":"string","maxLength":1000,"description":"Required for fix: what to change. Quoted in the next round."},"overrideQa":{"type":"boolean","description":"Approve pieces that failed QA anyway."}}}}}},"responses":{"200":{"description":"Decided. A piece changes state only when all its bookings succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"round":{"type":"integer"},"changed":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"array","items":{"type":"object","properties":{"pieceId":{"type":"string"},"reason":{"type":"string"}}}},"results":{"type":"array","items":{"type":"object","properties":{"pieceId":{"type":"string"},"ok":{"type":"boolean"},"error":{"type":"string"},"bookings":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"ok":{"type":"boolean"},"result":{"type":"string","enum":["approved","held","unchanged","failed"]},"error":{"type":"string"}}}}}}}}}}}},"403":{"description":"Missing scope, viewer role, or reviewer rules"},"404":{"description":"Not found"},"422":{"description":"Bad body (e.g. fix without note)"}}}},"/api/v2/campaigns/analytics":{"get":{"summary":"Campaigns first: running and recent campaigns with their numbers","description":"Running, planned and recently finished campaigns (organic, paid or mixed) with posts published of planned, reach, impressions, engagements, link clicks, spend and cost per result, plus each campaign's goal and success measure, a small daily trend, and `overlay`: the success measure and reach to date by day of campaign, for the default side-by-side charts. `aggregate` is all of them together with a daily series. Posts in no campaign roll up under `notInCampaign`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"includeUnassigned","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include the \"Not in a campaign\" roll-up (default true)."}],"responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"compareMax":{"type":"integer"},"aggregate":{"type":"object","description":"All the campaigns listed, together: totals, and a daily series over the last `aggregateDays` (admin config).","properties":{"campaigns":{"type":"integer"},"live":{"type":"integer"},"postsPublished":{"type":"integer"},"postsPlanned":{"type":"integer"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"impressions":{"type":"number"},"engagements":{"type":"number"},"linkClicks":{"type":"number"},"spendMinor":{"type":"integer","nullable":true,"description":"null when no campaign is paid or currencies differ."},"currency":{"type":"string","nullable":true},"series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"impressions":{"type":"number"},"engagements":{"type":"number"},"clicks":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"spendMinor":{"type":"integer"}}}},"window":{"type":"object","properties":{"fromDate":{"type":"string"},"toDate":{"type":"string"}}}}},"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"objective":{"type":"string","nullable":true},"kind":{"type":"string","enum":["organic","paid","mixed"]},"startDate":{"type":"number","description":"Epoch ms."},"endDate":{"type":"number","description":"Epoch ms."},"window":{"type":"object","properties":{"fromDate":{"type":"string"},"toDate":{"type":"string"}}},"totals":{"type":"object","properties":{"postsPublished":{"type":"integer"},"postsPlanned":{"type":"integer"},"postsWithResults":{"type":"integer"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"organicReach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"impressions":{"type":"number"},"engagements":{"type":"number"},"linkClicks":{"type":"number"},"paid":{"type":"object","nullable":true,"description":"Paid totals from the linked ad campaigns; null when the campaign has no paid results (or the plan has no ads).","properties":{"spendMinor":{"type":"integer"},"currency":{"type":"string","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"clicks":{"type":"number"},"linkClicks":{"type":"number","nullable":true,"description":"null = not reported by any network."},"leads":{"type":"number","nullable":true,"description":"null = not reported by any network."},"conversions":{"type":"number","nullable":true,"description":"null = not reported by any network."},"resultMetric":{"type":"string","description":"Which measure is the \"result\" for this objective (admin config)."},"results":{"type":"number","nullable":true,"description":"null = not reported by any network."},"costPerResultMinor":{"type":"number","nullable":true,"description":"Per result, or per 1000 when the result is impressions or reach."}}}}},"spark":{"type":"array","items":{"type":"number"},"description":"Daily impressions over the window."},"mixedCurrency":{"type":"boolean"},"truncated":{"type":"boolean","description":"More posts than the read cap; totals cover the first ones."},"url":{"type":"string","description":"The campaign page in flayr."},"success":{"type":"object","description":"The goal and the measure its success is shown by (admin config: successMetricByObjective).","properties":{"objective":{"type":"string","nullable":true},"metric":{"type":"string","enum":["reach","impressions","engagements","engagementRate","linkClicks","clickRate","results"]},"value":{"type":"number","nullable":true,"description":"Rates are fractions (0.034 = 3.4%). null = not reported."},"unit":{"type":"string","enum":["count","rate"]},"postsPace":{"type":"number","nullable":true,"description":"Share of planned posts published, 0..1; null when nothing was planned."},"timeElapsed":{"type":"number","description":"Share of the campaign dates that have passed, 0..1."}}},"seriesBasis":{"type":"object","description":"`stored`: organic days are growth recorded daily since `storedFrom` (earlier days estimated by publish day). `publishDay`: no stored day yet, each post's lifetime results on its publish day.","properties":{"kind":{"type":"string","enum":["stored","publishDay"]},"storedFrom":{"type":"string","nullable":true}}},"overlay":{"type":"object","description":"Cumulative success measure and reach by day of the campaign, so campaigns overlay (by date or by campaign day). null = not reported, never 0.","properties":{"metric":{"type":"string","enum":["reach","impressions","engagements","engagementRate","linkClicks","clickRate","results"]},"unit":{"type":"string","enum":["count","rate"]},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"day":{"type":"integer","description":"1 = first day of the campaign."},"success":{"type":"number","nullable":true,"description":"null = not reported by any network."},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."}}}}}}}}},"notInCampaign":{"type":"object","nullable":true,"properties":{"label":{"type":"string"},"window":{"type":"object","properties":{"fromDate":{"type":"string"},"toDate":{"type":"string"}}},"totals":{"type":"object","properties":{"postsPublished":{"type":"integer"},"postsPlanned":{"type":"integer"},"postsWithResults":{"type":"integer"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"organicReach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"impressions":{"type":"number"},"engagements":{"type":"number"},"linkClicks":{"type":"number"},"paid":{"type":"object","nullable":true,"description":"Paid totals from the linked ad campaigns; null when the campaign has no paid results (or the plan has no ads).","properties":{"spendMinor":{"type":"integer"},"currency":{"type":"string","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"clicks":{"type":"number"},"linkClicks":{"type":"number","nullable":true,"description":"null = not reported by any network."},"leads":{"type":"number","nullable":true,"description":"null = not reported by any network."},"conversions":{"type":"number","nullable":true,"description":"null = not reported by any network."},"resultMetric":{"type":"string","description":"Which measure is the \"result\" for this objective (admin config)."},"results":{"type":"number","nullable":true,"description":"null = not reported by any network."},"costPerResultMinor":{"type":"number","nullable":true,"description":"Per result, or per 1000 when the result is impressions or reach."}}}}},"spark":{"type":"array","items":{"type":"number"},"description":"Daily impressions over the window."},"truncated":{"type":"boolean"}}}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan has no analytics (or no campaign builder)"},"403":{"description":"The key lacks the read scope"},"429":{"description":"Rate limited"}}}},"/api/v2/campaigns/{id}/analytics":{"get":{"summary":"One campaign's full analytics","description":"Reach and engagement over time, per network, best and worst posts, and for paid the split by ad. `previousCampaign` names the one to compare against, with its `overlay`; `trend` compares the two at the same day of campaign.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign analytics","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"objective":{"type":"string","nullable":true},"kind":{"type":"string","enum":["organic","paid","mixed"]},"startDate":{"type":"number","description":"Epoch ms."},"endDate":{"type":"number","description":"Epoch ms."},"window":{"type":"object","properties":{"fromDate":{"type":"string"},"toDate":{"type":"string"}}},"totals":{"type":"object","properties":{"postsPublished":{"type":"integer"},"postsPlanned":{"type":"integer"},"postsWithResults":{"type":"integer"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"organicReach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"impressions":{"type":"number"},"engagements":{"type":"number"},"linkClicks":{"type":"number"},"paid":{"type":"object","nullable":true,"description":"Paid totals from the linked ad campaigns; null when the campaign has no paid results (or the plan has no ads).","properties":{"spendMinor":{"type":"integer"},"currency":{"type":"string","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"clicks":{"type":"number"},"linkClicks":{"type":"number","nullable":true,"description":"null = not reported by any network."},"leads":{"type":"number","nullable":true,"description":"null = not reported by any network."},"conversions":{"type":"number","nullable":true,"description":"null = not reported by any network."},"resultMetric":{"type":"string","description":"Which measure is the \"result\" for this objective (admin config)."},"results":{"type":"number","nullable":true,"description":"null = not reported by any network."},"costPerResultMinor":{"type":"number","nullable":true,"description":"Per result, or per 1000 when the result is impressions or reach."}}}}},"spark":{"type":"array","items":{"type":"number"},"description":"Daily impressions over the window."},"mixedCurrency":{"type":"boolean"},"truncated":{"type":"boolean","description":"More posts than the read cap; totals cover the first ones."},"url":{"type":"string","description":"The campaign page in flayr."},"success":{"type":"object","description":"The goal and the measure its success is shown by (admin config: successMetricByObjective).","properties":{"objective":{"type":"string","nullable":true},"metric":{"type":"string","enum":["reach","impressions","engagements","engagementRate","linkClicks","clickRate","results"]},"value":{"type":"number","nullable":true,"description":"Rates are fractions (0.034 = 3.4%). null = not reported."},"unit":{"type":"string","enum":["count","rate"]},"postsPace":{"type":"number","nullable":true,"description":"Share of planned posts published, 0..1; null when nothing was planned."},"timeElapsed":{"type":"number","description":"Share of the campaign dates that have passed, 0..1."}}},"seriesBasis":{"type":"object","description":"`stored`: organic days are growth recorded daily since `storedFrom` (earlier days estimated by publish day). `publishDay`: no stored day yet, each post's lifetime results on its publish day.","properties":{"kind":{"type":"string","enum":["stored","publishDay"]},"storedFrom":{"type":"string","nullable":true}}},"overlay":{"type":"object","description":"Cumulative success measure and reach by day of the campaign, so campaigns overlay (by date or by campaign day). null = not reported, never 0.","properties":{"metric":{"type":"string","enum":["reach","impressions","engagements","engagementRate","linkClicks","clickRate","results"]},"unit":{"type":"string","enum":["count","rate"]},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"day":{"type":"integer","description":"1 = first day of the campaign."},"success":{"type":"number","nullable":true,"description":"null = not reported by any network."},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."}}}}}},"series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"impressions":{"type":"number"},"engagements":{"type":"number"},"clicks":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"spendMinor":{"type":"integer"}}}},"networks":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"kind":{"type":"string","enum":["organic","paid"]},"posts":{"type":"integer"},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"engagements":{"type":"number"},"clicks":{"type":"number"},"spendMinor":{"type":"integer","nullable":true}}}},"bestPosts":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"text":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"publishedAt":{"type":"number","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"engagements":{"type":"number"},"clicks":{"type":"number"}}}},"worstPosts":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"text":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"publishedAt":{"type":"number","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"engagements":{"type":"number"},"clicks":{"type":"number"}}}},"ads":{"type":"array","items":{"type":"object","properties":{"adId":{"type":"string"},"name":{"type":"string"},"network":{"type":"string","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"clicks":{"type":"number"},"spendMinor":{"type":"integer"},"results":{"type":"number","nullable":true,"description":"null = not reported by any network."},"costPerResultMinor":{"type":"number","nullable":true}}}},"bestAds":{"type":"array","items":{"type":"object","properties":{"adId":{"type":"string"},"name":{"type":"string"},"network":{"type":"string","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"clicks":{"type":"number"},"spendMinor":{"type":"integer"},"results":{"type":"number","nullable":true,"description":"null = not reported by any network."},"costPerResultMinor":{"type":"number","nullable":true}}}},"worstAds":{"type":"array","items":{"type":"object","properties":{"adId":{"type":"string"},"name":{"type":"string"},"network":{"type":"string","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"clicks":{"type":"number"},"spendMinor":{"type":"integer"},"results":{"type":"number","nullable":true,"description":"null = not reported by any network."},"costPerResultMinor":{"type":"number","nullable":true}}}}}},"previousCampaign":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"objective":{"type":"string","nullable":true},"overlay":{"type":"object","description":"Cumulative success measure and reach by day of the campaign, so campaigns overlay (by date or by campaign day). null = not reported, never 0.","properties":{"metric":{"type":"string","enum":["reach","impressions","engagements","engagementRate","linkClicks","clickRate","results"]},"unit":{"type":"string","enum":["count","rate"]},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"day":{"type":"integer","description":"1 = first day of the campaign."},"success":{"type":"number","nullable":true,"description":"null = not reported by any network."},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."}}}}}},"compareUrl":{"type":"string"}}},"trend":{"type":"object","nullable":true,"description":"null when there is no previous campaign.","properties":{"success":{"type":"object","nullable":true,"description":"This campaign against the previous one at the same day of campaign. `previous` is null when the goals use different measures.","properties":{"day":{"type":"integer"},"current":{"type":"number","nullable":true,"description":"null = not reported by any network."},"previous":{"type":"number","nullable":true,"description":"null = not reported by any network."},"change":{"type":"number","nullable":true,"description":"Fraction (0.5 = +50%)."}}},"reach":{"type":"object","nullable":true,"description":"This campaign against the previous one at the same day of campaign. `previous` is null when the goals use different measures.","properties":{"day":{"type":"integer"},"current":{"type":"number","nullable":true,"description":"null = not reported by any network."},"previous":{"type":"number","nullable":true,"description":"null = not reported by any network."},"change":{"type":"number","nullable":true,"description":"Fraction (0.5 = +50%)."}}}}}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan has no analytics (or no campaign builder)"},"403":{"description":"The key lacks the read scope"},"404":{"description":"Not found (or another brand)"},"429":{"description":"Rate limited"}}}},"/api/v2/campaigns/compare":{"get":{"summary":"Compare campaigns side by side","description":"Two or more campaigns (organic vs organic, organic vs paid, this one against the previous one): totals, per-network split, best/worst posts and cumulative series by day since each start, so they overlay.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated campaign ids (at least two, at most `compareMax`)."}],"responses":{"200":{"description":"Comparison","content":{"application/json":{"schema":{"type":"object","properties":{"compareMax":{"type":"integer"},"url":{"type":"string"},"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"objective":{"type":"string","nullable":true},"kind":{"type":"string","enum":["organic","paid","mixed"]},"startDate":{"type":"number","description":"Epoch ms."},"endDate":{"type":"number","description":"Epoch ms."},"window":{"type":"object","properties":{"fromDate":{"type":"string"},"toDate":{"type":"string"}}},"totals":{"type":"object","properties":{"postsPublished":{"type":"integer"},"postsPlanned":{"type":"integer"},"postsWithResults":{"type":"integer"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"organicReach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"impressions":{"type":"number"},"engagements":{"type":"number"},"linkClicks":{"type":"number"},"paid":{"type":"object","nullable":true,"description":"Paid totals from the linked ad campaigns; null when the campaign has no paid results (or the plan has no ads).","properties":{"spendMinor":{"type":"integer"},"currency":{"type":"string","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"clicks":{"type":"number"},"linkClicks":{"type":"number","nullable":true,"description":"null = not reported by any network."},"leads":{"type":"number","nullable":true,"description":"null = not reported by any network."},"conversions":{"type":"number","nullable":true,"description":"null = not reported by any network."},"resultMetric":{"type":"string","description":"Which measure is the \"result\" for this objective (admin config)."},"results":{"type":"number","nullable":true,"description":"null = not reported by any network."},"costPerResultMinor":{"type":"number","nullable":true,"description":"Per result, or per 1000 when the result is impressions or reach."}}}}},"spark":{"type":"array","items":{"type":"number"},"description":"Daily impressions over the window."},"mixedCurrency":{"type":"boolean"},"truncated":{"type":"boolean","description":"More posts than the read cap; totals cover the first ones."},"url":{"type":"string","description":"The campaign page in flayr."},"success":{"type":"object","description":"The goal and the measure its success is shown by (admin config: successMetricByObjective).","properties":{"objective":{"type":"string","nullable":true},"metric":{"type":"string","enum":["reach","impressions","engagements","engagementRate","linkClicks","clickRate","results"]},"value":{"type":"number","nullable":true,"description":"Rates are fractions (0.034 = 3.4%). null = not reported."},"unit":{"type":"string","enum":["count","rate"]},"postsPace":{"type":"number","nullable":true,"description":"Share of planned posts published, 0..1; null when nothing was planned."},"timeElapsed":{"type":"number","description":"Share of the campaign dates that have passed, 0..1."}}},"seriesBasis":{"type":"object","description":"`stored`: organic days are growth recorded daily since `storedFrom` (earlier days estimated by publish day). `publishDay`: no stored day yet, each post's lifetime results on its publish day.","properties":{"kind":{"type":"string","enum":["stored","publishDay"]},"storedFrom":{"type":"string","nullable":true}}},"overlay":{"type":"object","description":"Cumulative success measure and reach by day of the campaign, so campaigns overlay (by date or by campaign day). null = not reported, never 0.","properties":{"metric":{"type":"string","enum":["reach","impressions","engagements","engagementRate","linkClicks","clickRate","results"]},"unit":{"type":"string","enum":["count","rate"]},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"day":{"type":"integer","description":"1 = first day of the campaign."},"success":{"type":"number","nullable":true,"description":"null = not reported by any network."},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."}}}}}},"networks":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"kind":{"type":"string","enum":["organic","paid"]},"posts":{"type":"integer"},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"engagements":{"type":"number"},"clicks":{"type":"number"},"spendMinor":{"type":"integer","nullable":true}}}},"bestPosts":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"text":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"publishedAt":{"type":"number","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"engagements":{"type":"number"},"clicks":{"type":"number"}}}},"worstPosts":{"type":"array","items":{"type":"object","properties":{"postId":{"type":"string"},"text":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"publishedAt":{"type":"number","nullable":true},"impressions":{"type":"number"},"reach":{"type":"number","nullable":true,"description":"null = not reported by any network."},"engagements":{"type":"number"},"clicks":{"type":"number"}}}},"cumulative":{"type":"array","items":{"type":"object","properties":{"day":{"type":"integer"},"impressions":{"type":"number"},"engagements":{"type":"number"},"clicks":{"type":"number"},"spendMinor":{"type":"integer"}}}}}}},"missing":{"type":"array","items":{"type":"string"}},"truncatedToMax":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan has no analytics (or no campaign builder)"},"403":{"description":"The key lacks the read scope"},"404":{"description":"None of the campaigns found"},"422":{"description":"Fewer than two ids, or a malformed id"},"429":{"description":"Rate limited"}}}},"/api/v2/ads/caps":{"get":{"tags":["API v2"],"summary":"Read the spend caps, agent ceilings and account limit headroom","security":[{"bearerAuth":[]}],"description":"The brand's activation caps and what is committed against them this month, the owner's agent ceilings, and the ad account spending limit with what is left of it. With `campaignId`, also what activating that campaign would answer right now (applied, approval_requested or refused), covering flayr's own checks; the ad network can still refuse the change. Read only. Needs the `read`, `ads:read` or another `ads:*` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"campaignId","in":"query","required":false,"schema":{"type":"string"},"description":"A campaign id (GET /api/v2/ads/campaigns) to forecast the activation of."},{"name":"platform","in":"query","required":false,"schema":{"type":"string"},"description":"FFE-1607: report the account limit of this network's selected ad account (meta, tiktok, linkedin, google, reddit, x, openai, pinterest or microsoft). Without it and without campaignId, the newest selection, which may be another network. Any other value answers 400."}],"responses":{"200":{"description":"Caps, ceilings and account limit","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"The brand these numbers belong to, or \"personal\"."},"month":{"type":"string","description":"The month the usage is counted in, UTC, e.g. 2026-11."},"caps":{"type":"object","description":"The activation spend caps and what is committed against the monthly one.","properties":{"monthlyMaxMinor":{"type":"integer","description":"Monthly activation cap."},"perCampaignMaxMinor":{"type":"integer","description":"Per-campaign activation cap."},"source":{"type":"string","enum":["default","global","org","user"],"description":"Where the caps come from; \"default\" means nobody has set them."},"committedThisMonthMinor":{"type":"integer","description":"What counts against the monthly cap: the maximum spend of the campaigns activated this month, except that an ended or stopped-for-good campaign counts only what it spent once that spend has synced."},"spentThisMonthMinor":{"type":"integer","description":"Synced spend of the campaigns activated this month, since they were activated."},"releasedThisMonthMinor":{"type":"integer","description":"Unspent maximum given back by ended and stopped-for-good campaigns (already left out of committedThisMonthMinor)."},"monthlyRemainingMinor":{"type":"integer","description":"What is left under the monthly cap (never below 0)."}}},"agentCeilings":{"type":"object","description":"The most an agent may set or activate without the owner (Ads > Spend controls). 0 = everything needs the owner.","properties":{"agentMaxMonthlyMinor":{"type":"integer","description":"Highest monthly cap an agent may set."},"agentMaxPerCampaignMinor":{"type":"integer","description":"Highest per-campaign cap an agent may set."},"agentMaxAccountSpendCapMinor":{"type":"integer","description":"Highest ad account spending limit an agent may set."},"agentMaxDailyActivationMinor":{"type":"integer","description":"Highest daily budget an agent may activate."}}},"blocked":{"type":"object","nullable":true,"description":"Set when no agent write can apply at all: ADS_NOT_OWNER (the key's owner is not an owner or admin of the brand) or ADS_KILL_SWITCH.","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"account":{"type":"object","nullable":true,"description":"The brand's selected ad account; null when none is selected.","properties":{"platform":{"type":"string"},"platformAdAccountId":{"type":"string"},"currency":{"type":"string"},"spendLimitMinor":{"type":"integer","description":"The account spending limit; null = no limit set.","nullable":true},"amountSpentMinor":{"type":"integer","description":"What the ad network counts against the limit; null when it could not be read.","nullable":true},"remainingMinor":{"type":"integer","description":"What is left under the limit; null without a limit or an amount spent.","nullable":true},"live":{"type":"boolean","description":"True when the limit and amount spent were just read from the ad network; false = the stored limit."},"limitSupported":{"type":"boolean","description":"False for ad networks with no account spending limit."},"limitRequired":{"type":"boolean","description":"True when activating needs an account spending limit."}}},"activation":{"type":"object","description":"Only with `campaignId`: what POST /api/v2/ads/campaigns/{id}/approve with activate: true would answer right now, for this key.","properties":{"campaignId":{"type":"string"},"dailyMinor":{"type":"integer","description":"The campaign's daily budget."},"maxSpendMinor":{"type":"integer","description":"The most the campaign can spend."},"currency":{"type":"string"},"outcome":{"type":"string","enum":["applied","approval_requested","refused"],"description":"applied = 200, it switches on; approval_requested = 202, the owner gets an approval request; refused = it does not apply, see code."},"code":{"type":"string","description":"refused only, e.g. ADS_MONTHLY_CAP_EXCEEDED, ADS_NO_ACCOUNT_LIMIT, SCOPE_REQUIRED."},"message":{"type":"string"},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's daily activation ceiling."},"approvalRequest":{"type":"string","enum":["pending"],"description":"An approval request for this activation is already waiting for the owner."},"viaGrant":{"type":"boolean","description":"True when the owner already approved this activation."},"requiredScope":{"type":"string","description":"SCOPE_REQUIRED only: the scope this key lacks for the activate call."}}}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing scope, a brand the key is not bound to, or ads not available"},"404":{"description":"Brand or campaign not found in this brand"},"502":{"description":"The caps could not be read"}}},"post":{"tags":["API v2"],"summary":"Set the activation spend caps","security":[{"bearerAuth":[]}],"description":"Sets the monthly and/or per-campaign activation caps, in cents. Lowering is always inside the ceiling; raising is applied up to the owner's agent ceiling. Needs the explicit `ads:budget` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"monthlyMaxMinor":{"type":"integer","description":"Monthly activation cap, whole cents (100 to 10000000)."},"perCampaignMaxMinor":{"type":"integer","description":"Per-campaign activation cap, whole cents (100 to 10000000)."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/accounts/spend-limit":{"post":{"tags":["API v2"],"summary":"Set the ad account spending limit","security":[{"bearerAuth":[]}],"description":"Sets the Meta ad account spending limit (account currency, e.g. 800 = $800). null removes the limit, which always needs the owner. Needs the explicit `ads:budget` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","spendCap"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"spendCap":{"type":"number","nullable":true,"description":"The new limit in the ad account currency, or null to remove it."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/ad-sets/{id}/placements":{"post":{"tags":["API v2"],"summary":"Edit ad set placements","security":[{"bearerAuth":[]}],"description":"Changes where an existing ad set runs. `excludeAudienceNetwork: true` sets the publisher platforms to facebook, instagram and messenger (automatic placements minus Audience Network); or send an explicit publisherPlatforms list. `id` is the flayr ad set id or the network ad set id. Needs the explicit `ads:manage` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"excludeAudienceNetwork":{"type":"boolean"},"publisherPlatforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","messenger","threads","audience_network","whatsapp"]}}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/ad-sets/{id}/dataset":{"post":{"tags":["API v2"],"summary":"Attach a dataset (pixel) to an ad set","security":[{"bearerAuth":[]}],"description":"Sets the ad set's promoted object to the Meta dataset (pixel) and, optionally, the conversion event. Applies to the ad set; ad-level tracking specs are not changed. Needs the explicit `ads:manage` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","pixelId"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"pixelId":{"type":"string","description":"The Meta dataset (pixel) id, digits."},"customEventType":{"type":"string","description":"Meta standard event, e.g. PURCHASE, LEAD."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/campaigns/{id}/approve":{"post":{"tags":["API v2"],"summary":"Approve (and activate) a proposed campaign","security":[{"bearerAuth":[]}],"description":"Approves a proposed campaign (`ads:manage` or `ads:activate`). With `activate: true` it also switches the campaign on through the normal activation gate (caps, ad account checks), when its daily spend is within the owner's per-day agent ceiling; that needs `ads:activate`. Needs the explicit `ads:manage` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"activate":{"type":"boolean","description":"Also switch it on. Needs ads:activate."},"idempotencyKey":{"type":"string","description":"Optional; repeats with the same key do not re-run the activation."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/campaigns/{id}/budget":{"post":{"tags":["API v2"],"summary":"Scale a campaign budget","security":[{"bearerAuth":[]}],"description":"Sets the campaign-level budget to `budgetMinor`, keeping its type. A daily budget is held to the owner's per-day agent ceiling, a lifetime budget to the per-campaign ceiling; scaling down is always inside it. Runs the dashboard's own budget edit (budget rules, activation spend caps, the ad network write). Needs the explicit `ads:manage` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","budgetMinor"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"budgetMinor":{"type":"integer","description":"The new budget, whole cents (e.g. 4000 = $40), daily or lifetime as the campaign is set up."},"idempotencyKey":{"type":"string","description":"Optional; a retry with the same key does not apply the change twice."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/targeting/search":{"get":{"tags":["API v2"],"summary":"Search ad targeting (interests)","security":[{"bearerAuth":[]}],"description":"Searches the brand's selected ad account for targeting ids by name (read-only). Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"2+ characters; shorter answers no results."},{"name":"dimension","in":"query","required":false,"schema":{"type":"string","enum":["interest","behavior","geo","income","community","conversationKeyword","interestKeyword","hashtag"]},"description":"Default interest. community and conversationKeyword: Reddit only. interestKeyword and hashtag (FFE-1607): TikTok only; put interestKeyword ids in targeting.interests as `keyword:<id>`, and hashtag ids (`hashtag:<id>`) in targeting.behaviors."},{"name":"geoType","in":"query","required":false,"schema":{"type":"string"},"description":"dimension geo only."},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string"},"description":"ISO alpha-2."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["tiktok","meta","reddit"]},"description":"FFE-1607: search this network's selected ad account. Without it, the newest selection, which may be another network."}],"responses":{"200":{"description":"Matches","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"dimension":{"type":"string"},"path":{"type":"array","items":{"type":"string"}},"audienceSize":{"type":"integer","nullable":true}}}}}}}}},"400":{"description":"Invalid query, or no ad account selected for the brand"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED)"},"502":{"description":"The ad network did not answer"}}}},"/api/v2/ads/lead-forms":{"get":{"tags":["API v2"],"summary":"List Instant Forms (lead forms)","security":[{"bearerAuth":[]}],"description":"The Meta Instant Forms on the brand's selected ad account. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lead forms","content":{"application/json":{"schema":{"type":"object","properties":{"forms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"privacyPolicyUrl":{"type":"string"}}}},"nextCursor":{"type":"string","nullable":true}}}}}},"400":{"description":"No Meta ad account selected for the brand"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED)"},"502":{"description":"The ad network did not answer"}}},"post":{"tags":["API v2"],"summary":"Create an Instant Form (lead form)","security":[{"bearerAuth":[]}],"description":"Creates a Meta Instant Form on the brand's selected ad account with the same builder and limits as the dashboard (question count, option count, label lengths). One vendor call, never retried. The response carries `formId`, to use as `leadGenFormId` when creating the lead campaign. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","name","privacyPolicyUrl","questions"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"name":{"type":"string"},"privacyPolicyUrl":{"type":"string","description":"Absolute https URL."},"questions":{"type":"array","items":{"type":"object"},"description":"Meta question objects, e.g. { \"type\": \"EMAIL\" }, { \"type\": \"FULL_NAME\" }, { \"type\": \"CUSTOM\", \"label\": \"…\", \"options\": [{ \"key\": \"a\", \"value\": \"A\" }] }."},"contextCard":{"type":"object","description":"Optional intro card shown before the questions."},"thankYouTitle":{"type":"string"},"thankYouBody":{"type":"string"},"thankYouButtonText":{"type":"string"},"thankYouButtonType":{"type":"string","enum":["VIEW_WEBSITE"]},"thankYouWebsiteUrl":{"type":"string","description":"https URL; required with a VIEW_WEBSITE button."},"followUpActionUrl":{"type":"string","description":"Optional https URL the thank-you button opens."},"privacyPolicyLinkText":{"type":"string"},"locale":{"type":"string"},"isOptimizedForQuality":{"type":"boolean"},"platform":{"type":"string","enum":["metaads"],"description":"Optional; Meta only."},"idempotencyKey":{"type":"string","description":"Optional; 1-255 characters of A-Z a-z 0-9 . _ : -. Repeats with the same key are safe to send."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/conversions/test-events":{"post":{"tags":["API v2"],"summary":"Send one test conversion event (Meta test_event_code)","security":[{"bearerAuth":[]}],"description":"Sends ONE server-side CompleteRegistration to a Meta pixel on the brand's selected ad account, with Meta's `test_event_code`, to prove the Conversions API path delivers. It is the event a real sign-up sends, for a made-up person. It never sends without `testEventCode`, creates no campaign, ad, audience or pixel, and spends nothing. The pixel must be one Meta lists for the ad account: otherwise 409 `ADS_PIXEL_NOT_ON_AD_ACCOUNT` with the pixels Meta does list and the step to share it. 200 `outcome: \"delivered\"` only when Meta counted the event and failed none; 502 `outcome: \"rejected\"` carries Meta's error codes (`failureCodes`), never its messages. One vendor call, never retried. Meta shows the event under Events Manager → the dataset → Test events while that tab is open with the same code, and also counts it in the dataset totals. Needs the explicit `ads:manage` scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentName","reason","testEventCode"],"properties":{"agentName":{"type":"string","description":"Which agent is acting. Shown to the owner in Ads > Agent activity."},"reason":{"type":"string","description":"Why the agent is doing this. Shown to the owner and kept in the audit trail."},"testEventCode":{"type":"string","description":"The code from Meta Events Manager → the dataset → Test events (e.g. TEST12345). Up to 32 letters, digits, \"_\" or \"-\"."},"pixelId":{"type":"string","description":"Optional Meta pixel (dataset) id. Default: the pixel saved for the ad account, or its only active pixel."}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"202":{"description":"Above the owner's ceiling: an owner approval request was created (not an error)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"400":{"description":"Invalid body, or agentName / reason missing"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing explicit scope (code SCOPE_REQUIRED), not owner/admin, or the kill switch is on","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"404":{"description":"Not found in this brand"},"409":{"description":"Refused (e.g. no ad account selected)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}},"502":{"description":"The ad network refused the change (audited as failed)","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","approval_requested","refused","failed","proceed"]},"actionId":{"type":"string","description":"The audit row (GET /api/v2/ads/agent/activity)."},"requestId":{"type":"string","description":"approval_requested only: the owner approval request."},"approvalId":{"type":"string","description":"approval_requested only: the same id as requestId, for approvals_decide / POST /api/v2/approvals/{id}."},"approvalUrl":{"type":"string","description":"approval_requested only: the owner's one-click deep link (/approve/{id}): it switches to the request's workspace and brand and opens the item. Absent when the owner set approvals to API/MCP/chat only (assistantOnly)."},"assistantOnly":{"type":"boolean","description":"approval_requested only: true when the owner approves by API, MCP or chat only. No link is sent; the owner decides approvalId with approvals_decide or in flayr chat."},"ceilingMinor":{"type":"integer","description":"approval_requested only: the owner's ceiling, in cents."},"requestedMinor":{"type":"integer","description":"approval_requested only: what was asked for, in cents."},"code":{"type":"string"},"message":{"type":"string"},"previous":{"type":"object","description":"The value before the change, when known."},"viaGrant":{"type":"boolean","description":"True when this call used an owner approval."},"sync":{"type":"object","description":"Resume, when applied (FFE-1607): whether flayr asked the ad network for the campaign tree right away so the read-back reflects the new state. A failed request never fails the resume.","properties":{"requested":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}}},"/api/v2/ads/agent/activity":{"get":{"tags":["API v2"],"summary":"Agent activity","security":[{"bearerAuth":[]}],"description":"Recent agent actions (key, agent name, reason, outcome), pending owner approval requests and the owner's agent ceilings. Needs the read scope.","parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"responses":{"200":{"description":"Agent activity","content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object"}},"pending":{"type":"array","items":{"type":"object"}},"ceilings":{"type":"object","properties":{"agentMaxMonthlyMinor":{"type":"integer"},"agentMaxPerCampaignMinor":{"type":"integer"},"agentMaxAccountSpendCapMinor":{"type":"integer"},"agentMaxDailyActivationMinor":{"type":"integer"}}},"canAdminister":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available"}}}},"/api/v2/ads/deep-dives":{"get":{"tags":["API v2"],"summary":"List saved deep dives","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"Recent saved deep-dive runs for the brand (headers and finding counts). No cross-org access.","responses":{"200":{"description":"Saved runs","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand, snapshot or run"}}},"post":{"tags":["API v2"],"summary":"Run a deep dive on a saved snapshot","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"Charges Embers through the ledger (free inside the re-run window for an unchanged snapshot) after `confirmEmbers` matches the current quote. Changes no ad, budget or campaign. A failed run refunds its charge.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["snapshotId","confirmEmbers"],"properties":{"snapshotId":{"type":"string"},"confirmEmbers":{"type":"integer","minimum":0,"description":"The total Embers from the quote you agreed to."}}}}}},"responses":{"200":{"description":"Existing report reused at no charge","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Saved run id and Embers charged","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Not enough Embers"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand, snapshot or run"},"409":{"description":"The price changed; the new quote is in the body"}}}},"/api/v2/ads/deep-dives/quote":{"get":{"tags":["API v2"],"summary":"Quote a deep dive","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"snapshotId","in":"query","required":true,"schema":{"type":"string"},"description":"A saved ads data snapshot id."}],"description":"The Embers price before running, and whether a recent run makes this one free. Charges nothing.","responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand, snapshot or run"}}}},"/api/v2/ads/deep-dives/compare":{"get":{"tags":["API v2"],"summary":"Compare two deep dives","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"before","in":"query","required":true,"schema":{"type":"string"},"description":"The older run id."},{"name":"after","in":"query","required":true,"schema":{"type":"string"},"description":"The newer run id."}],"description":"Per-finding new / resolved / worse / better / unchanged, plus metric deltas.","responses":{"200":{"description":"Comparison","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand, snapshot or run"}}}},"/api/v2/ads/campaigns/{id}/checkpoints":{"get":{"tags":["API v2"],"summary":"Read a campaign's scheduled check-ins","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Whether check-ins (default day 3, 7 and 14 after activation) are on, the Embers price of each, and every past check-in. Charges nothing.","responses":{"200":{"description":"Check-ins","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand, snapshot or run"}}},"post":{"tags":["API v2"],"summary":"Switch a campaign's scheduled check-ins on or off","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Owner or admin only. Switching on makes each future check-in charge `checkpointEmbers` (a check-in under the minimum spend is skipped free), so it needs `confirmEmbers` equal to that price. Changes no ad, budget or campaign.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"confirmEmbers":{"type":"integer","minimum":0,"description":"checkpointEmbers from the GET, required to switch on."}}}}}},"responses":{"200":{"description":"The new setting and the per-check-in price","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand, snapshot or run"},"409":{"description":"confirmEmbers missing or not the current price; the price is in the body"}}}},"/api/v2/ads/deep-dives/{id}":{"get":{"tags":["API v2"],"summary":"Read or export one deep dive","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","markdown","csv","pdf"],"default":"json"}}],"description":"The stored report. markdown, csv and pdf render the stored row exactly.","responses":{"200":{"description":"Deep dive (or the exported file)","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand, snapshot or run"}}}},"/api/v2/ads/learned-insights":{"get":{"tags":["API v2"],"summary":"Read the ads insights library (FFE-1076)","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"platform","in":"query","required":false,"schema":{"type":"string"},"description":"A network (facebook, instagram, tiktok...). Adds the do/avoid suggestions for a new campaign there."},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["experiment","deep_dive"]}}],"description":"What finished experiments and deep-dive verdicts confirmed in at least the configured number of runs showed, worked or not. Deep-dive insights carry evidence and a report link. Read only; no cross-org access.","responses":{"200":{"description":"Insights and, with platform, suggestions","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad platform or source"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, or another brand for a brand-bound key"},"404":{"description":"Unknown brand, snapshot or run"}}}},"/api/v2/ads/imports":{"get":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"}},{"name":"network","in":"query","required":true,"schema":{"type":"string","description":"Ad network, e.g. meta, linkedin, tiktok, google, x."}},{"name":"adAccountId","in":"query","required":true,"schema":{"type":"string","description":"The ad account selected for this network in the active brand."}}],"summary":"Read campaign import state","responses":{"200":{"description":"Import state or null. Counts are processed rows, not spend totals. partial marks truncated hierarchy; fromDate/toDate describe daily metric coverage."},"404":{"description":"Account unavailable in this workspace."}}},"post":{"tags":["API v2"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"}}],"summary":"Import one page of prior campaigns","description":"Reads connected-account metadata and daily metrics into local tables, idempotently. No vendor writes or spend. Repeat on in_progress; done completes a pass; blocked is resumable. A new call after done starts another pass. No guarantee of history predating the connection; no Meta Marketing API or file import.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["network","adAccountId"],"properties":{"network":{"type":"string","description":"Ad network, e.g. meta, linkedin, tiktok, google, x."},"adAccountId":{"type":"string","description":"The ad account selected for this network in the active brand."}}}}}},"responses":{"200":{"description":"status: done, in_progress or blocked."},"403":{"description":"Account or workspace not accessible."},"409":{"description":"status: busy; another call holds the page lease."}}}},"/api/v2/ads/imports/files":{"get":{"tags":["API v2"],"summary":"List stats file imports","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"The workspace's imports of prior campaign stats, newest first, with row counts and whether each was undone. No cross-org access.","responses":{"200":{"description":"Imports","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, imports switched off, or another brand for a brand-bound key"},"404":{"description":"Unknown brand or import"}}},"post":{"tags":["API v2"],"summary":"Import prior campaign stats from an export","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"Writes the rows of an Ads Manager export (CSV or XLSX) as imported reporting rows, in one batch that can be undone. A synced row is never overwritten: only metrics it does not report are filled. Importing the same file twice changes nothing. Spends nothing, calls no ad network and changes no budget. Preview first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","fileName"],"properties":{"platform":{"type":"string","enum":["metaads","tiktokads","googleads","linkedinads","redditads","pinterestads","snapchat"],"description":"The ad network the export came from."},"fileName":{"type":"string","maxLength":300,"description":"The export file name. Kept with each imported row."},"csv":{"type":"string","description":"The export as CSV text. Send exactly one of csv or xlsxBase64."},"xlsxBase64":{"type":"string","description":"An .xlsx export, base64 encoded (standard alphabet, no line breaks). The first sheet is read."},"mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Field to column header, for columns the network preset does not recognise. Fields: date, dateEnd, level, campaignId, campaignName, adsetId, adsetName, adId, adName, accountId, spend, currency, impressions, reach, clicks, linkClicks, results, resultType, leads, conversions, thruplays, videoViews3s, videoViews. Omit to use the preset; the preview returns the mapping it found."},"currency":{"type":"string","description":"A 3-letter currency for a file with no currency column, such as USD."},"timezone":{"type":"string","description":"The ad account time zone (IANA, such as America/Chicago), used for timestamps that carry an offset. Default: UTC. A plain date is kept as written."},"level":{"type":"string","enum":["campaign","adset","ad"],"description":"The row level, for rows with no level cell. Default: the deepest level the mapped columns identify."},"dateOrder":{"type":"string","enum":["mdy","dmy"],"description":"How to read a date such as 04/05/2026. Default: mdy (month first)."},"adAccountId":{"type":"string","description":"The ad account the export belongs to, stored with each row."}}}}}},"responses":{"200":{"description":"Nothing to write: every row was already stored (batchId is null)","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"The import batch id, row counts, skipped rows by line number and conflicts","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The body is not a usable import request (missing platform or file, bad mapping, unreadable workbook)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, imports switched off, or another brand for a brand-bound key"},"404":{"description":"Unknown brand or import"},"413":{"description":"The file is over the size, row or object limit"},"422":{"description":"The file could not be read as a stats export (no header row, a required column not mapped, bad option)"}}}},"/api/v2/ads/imports/files/preview":{"post":{"tags":["API v2"],"summary":"Preview a stats file import","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."}],"description":"What the file would do, without writing: the detected column mapping, columns left unmapped, the first rows, malformed rows by line number, and each conflict with a synced row (the synced value is kept).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","fileName"],"properties":{"platform":{"type":"string","enum":["metaads","tiktokads","googleads","linkedinads","redditads","pinterestads","snapchat"],"description":"The ad network the export came from."},"fileName":{"type":"string","maxLength":300,"description":"The export file name. Kept with each imported row."},"csv":{"type":"string","description":"The export as CSV text. Send exactly one of csv or xlsxBase64."},"xlsxBase64":{"type":"string","description":"An .xlsx export, base64 encoded (standard alphabet, no line breaks). The first sheet is read."},"mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Field to column header, for columns the network preset does not recognise. Fields: date, dateEnd, level, campaignId, campaignName, adsetId, adsetName, adId, adName, accountId, spend, currency, impressions, reach, clicks, linkClicks, results, resultType, leads, conversions, thruplays, videoViews3s, videoViews. Omit to use the preset; the preview returns the mapping it found."},"currency":{"type":"string","description":"A 3-letter currency for a file with no currency column, such as USD."},"timezone":{"type":"string","description":"The ad account time zone (IANA, such as America/Chicago), used for timestamps that carry an offset. Default: UTC. A plain date is kept as written."},"level":{"type":"string","enum":["campaign","adset","ad"],"description":"The row level, for rows with no level cell. Default: the deepest level the mapped columns identify."},"dateOrder":{"type":"string","enum":["mdy","dmy"],"description":"How to read a date such as 04/05/2026. Default: mdy (month first)."},"adAccountId":{"type":"string","description":"The ad account the export belongs to, stored with each row."}}}}}},"responses":{"200":{"description":"Preview","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The body is not a usable import request (missing platform or file, bad mapping, unreadable workbook)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, imports switched off, or another brand for a brand-bound key"},"404":{"description":"Unknown brand or import"},"413":{"description":"The file is over the size, row or object limit"},"422":{"description":"The file could not be read as a stats export (no header row, a required column not mapped, bad option)"}}}},"/api/v2/ads/imports/files/{id}":{"get":{"tags":["API v2"],"summary":"Read one stats file import","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An import id from GET /api/v2/ads/imports/files."}],"description":"The import header and the campaigns, ad sets and ads it brought in, with their totals. A metric the file did not report is null, never 0.","responses":{"200":{"description":"Import","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, imports switched off, or another brand for a brand-bound key"},"404":{"description":"Unknown brand or import"}}}},"/api/v2/ads/imports/files/{id}/undo":{"post":{"tags":["API v2"],"summary":"Undo one stats file import","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"A brand id (GET /api/v2/brands) or \"personal\"; default: the key owner's active brand."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An import id from GET /api/v2/ads/imports/files."}],"description":"Removes the rows the import created and clears the metrics it filled on synced rows. Synced data is never touched. Undoing twice is a no-op.","responses":{"200":{"description":"Rows removed and rows un-filled","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Ads not available, imports switched off, or another brand for a brand-bound key"},"404":{"description":"Unknown brand or import"}}}},"/api/v2/campaign-shares":{"get":{"tags":["API v2"],"summary":"List sample campaign review links","description":"The review links of a brand, newest first, with the expiry choices a new link may use (`expiryDays`). No tokens: a token is returned once, when the link is made. Requires the write scope, and a key whose owner is an owner, admin or editor of the brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"Brand id (GET /api/v2/brands). Required for an account-wide key; a brand-bound key uses its own brand."}],"responses":{"200":{"description":"The brand's links","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"expiryDays":{"type":"array","items":{"type":"integer"},"description":"The values `expiresInDays` accepts for this brand."},"maxRequesterLength":{"type":"integer","description":"The longest `requester` this brand accepts."},"links":{"type":"array","items":{"type":"object","description":"A review link. The token is never part of it: it is in the answer that created the link, once.","properties":{"id":{"type":"string"},"title":{"type":"string"},"campaignLabel":{"type":"string","description":"The label whose drafts the link shows."},"active":{"type":"boolean","description":"False once revoked or expired."},"site":{"type":"string","nullable":true,"description":"The site the campaign was made from, as a bare host name (example.com)."},"requester":{"type":"string","nullable":true,"description":"Who the campaign was made for."},"createdAt":{"type":"string","format":"date-time","description":"When the link was made."},"expiresAt":{"type":"string","format":"date-time","description":"When the link stops working."},"revokedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the link was revoked."},"lastViewedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the page was last opened."}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the write scope, or cannot manage that brand or link. A link that does not exist answers the same."},"422":{"description":"`brandId` missing (account-wide key) or `personal`"},"429":{"description":"Rate or quota limit"}}},"post":{"tags":["API v2"],"summary":"Make a sample campaign review link","description":"Makes a public page that shows the brand's drafts carrying `campaignLabel`, where a reviewer approves or asks for changes with no login. The answer carries `token` and `url` ONCE: flayr stores only a hash, so they cannot be read again. Give `site` and `requester` together to put one line on the page (\"Made by flayr from the public pages of <site> for <requester>\"), or leave both out. Requires the write scope, and a key whose owner is an owner, admin or editor of the brand.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["campaignLabel","title","expiresInDays"],"additionalProperties":false,"properties":{"brandId":{"type":"string","description":"Brand id (GET /api/v2/brands). Required for an account-wide key; a brand-bound key uses its own brand."},"campaignLabel":{"type":"string","description":"The label on the drafts to show, e.g. `campaign:<campaign id>`. At least one draft of the brand must carry it."},"title":{"type":"string","description":"The heading of the public page."},"expiresInDays":{"type":"integer","description":"One of the brand's `expiryDays` (GET /api/v2/campaign-shares)."},"site":{"type":"string","description":"The public site the campaign was made from (example.com or a full address; stored as the host name). Give it with `requester`."},"requester":{"type":"string","description":"Who the campaign was made for: a name, no links. Give it with `site`."}}}}}},"responses":{"201":{"description":"Created. The only answer that carries the token.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string"},"campaignLabel":{"type":"string"},"title":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","description":"When the link stops working."},"site":{"type":"string","nullable":true,"description":"The site the campaign was made from, as a bare host name (example.com)."},"requester":{"type":"string","nullable":true,"description":"Who the campaign was made for."},"token":{"type":"string","description":"The secret in the link. Returned once."},"url":{"type":"string","format":"uri","description":"The public page to send to the reviewer. Returned once."}}}}}},"400":{"description":"Invalid JSON"},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the write scope, or cannot manage that brand or link. A link that does not exist answers the same."},"422":{"description":"Validation error, or a rule of the link (no drafts carry the label, an expiry that is not offered, too many active links)"},"429":{"description":"Rate or quota limit"}}}},"/api/v2/campaign-shares/{id}":{"get":{"tags":["API v2"],"summary":"Read the verdicts on a review link","description":"What the reviewer said through the link, draft by draft. Requires the write scope; a brand-bound key only reaches links of its own brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Review link id (GET /api/v2/campaign-shares)."}],"responses":{"200":{"description":"The verdicts","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"verdicts":{"type":"array","items":{"type":"object","properties":{"contentId":{"type":"string","description":"The draft the verdict is on (a v2 content id)."},"decision":{"type":"string","enum":["approve","changes","deny"],"description":"What the reviewer chose for this draft."},"comment":{"type":"string","nullable":true},"reviewerName":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time","description":"When the reviewer last changed it."}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the write scope, or cannot manage that brand or link. A link that does not exist answers the same."},"429":{"description":"Rate or quota limit"}}},"delete":{"tags":["API v2"],"summary":"Revoke a review link","description":"The link stops working at once and cannot be turned back on; make a new link instead. Verdicts already given stay readable. Safe to repeat. Requires the write scope; a brand-bound key only reaches links of its own brand.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Review link id (GET /api/v2/campaign-shares)."}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The key lacks the write scope, or cannot manage that brand or link. A link that does not exist answers the same."},"429":{"description":"Rate or quota limit"}}}},"/api/v2/pool/state":{"get":{"tags":["API v2"],"operationId":"v2PoolState","summary":"Trial posting-spot pool: public state plus admin counts","description":"Needs an API key with the explicit `pool:admin` scope (admin does NOT include it) whose owner is a super-admin. Free makes posts; the trial is for posting, and the pool gates when posting starts.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The pool","content":{"application/json":{"schema":{"type":"object","properties":{"public":{"type":"object","description":"What the landing page shows (spots, taken, open, waiting)."},"counts":{"type":"object","description":"size, byState, waiting, emailWaiting, payingMembers, oldestWaitingDays, events24h, unnotified24h"},"config":{"type":"object","description":"Ladder, thresholds, cooldown, notify fallback minutes, nudge period, workflowWebhookConfigured."},"lastExpandedAt":{"type":"number","nullable":true},"cooldownEndsAt":{"type":"number","nullable":true},"expandRefusal":{"type":"string","nullable":true,"enum":["pool_disabled","ladder_max","auto_expand_off","below_threshold","cooldown","not_applied"],"description":"Why an expand now would be refused; null when it would go ahead."}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"SCOPE_REQUIRED (no `pool:admin`) or SUPER_ADMIN_REQUIRED (the key owner is not a super-admin)"},"429":{"description":"Rate limited"}}}},"/api/v2/pool/expand":{"post":{"tags":["API v2"],"operationId":"v2PoolExpand","summary":"Ask to open the next ladder step of posting spots (the server re-checks and may refuse)","description":"Needs an API key with the explicit `pool:admin` scope (admin does NOT include it) whose owner is a super-admin. Free makes posts; the trial is for posting, and the pool gates when posting starts. The threshold-watcher workflow calls this. The server re-checks the ladder, autoExpand, the waiting and paying-member thresholds and the cooldown.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"Answer without writing anything."}}}}}},"responses":{"200":{"description":"Expanded, or refused with a reason","content":{"application/json":{"schema":{"type":"object","properties":{"expanded":{"type":"boolean"},"step":{"type":"integer"},"size":{"type":"integer"},"reason":{"type":"string","enum":["pool_disabled","ladder_max","auto_expand_off","below_threshold","cooldown","not_applied"]},"waiting":{"type":"integer"},"payingMembers":{"type":"integer"},"cooldownEndsAt":{"type":"number","nullable":true}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"SCOPE_REQUIRED (no `pool:admin`) or SUPER_ADMIN_REQUIRED (the key owner is not a super-admin)"},"429":{"description":"Rate limited"}}}},"/api/v2/pool/notify":{"post":{"tags":["API v2"],"operationId":"v2PoolNotify","summary":"Send the notification for one pool.* event, then ack it","description":"Needs an API key with the explicit `pool:admin` scope (admin does NOT include it) whose owner is a super-admin. Free makes posts; the trial is for posting, and the pool gates when posting starts. The notify-relay workflow calls this for each pool.* webhook. Sends the email (notifications stream; the recipient's \"Posting-spot pool\" email switch is honoured) and the in-app notice, then acks the event so the fallback watchdog stands down. Idempotent: a repeat answers `already`. A hold notice whose hold has ended answers `stale` and sends nothing.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["eventId"],"properties":{"eventId":{"type":"string","description":"The `eventId` field of the pool.* webhook body."},"channel":{"type":"string","enum":["all","email","in_app"],"description":"Default all."}}}}}},"responses":{"200":{"description":"Handled","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"eventId":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string","enum":["sent","already","stale","not_notifiable"]},"recipients":{"type":"integer"},"emailOnly":{"type":"integer","description":"Email-only waitlist addresses mailed."}}}}}},"400":{"description":"event_id_required or bad_channel"},"401":{"description":"Missing or invalid API key"},"403":{"description":"SCOPE_REQUIRED (no `pool:admin`) or SUPER_ADMIN_REQUIRED (the key owner is not a super-admin)"},"404":{"description":"unknown_event"},"429":{"description":"Rate limited"}}}},"/api/v2/pool/waitlist-digest":{"get":{"tags":["API v2"],"operationId":"v2PoolWaitlistDigest","summary":"What the waitlist nudger would do now (counts only)","description":"Needs an API key with the explicit `pool:admin` scope (admin does NOT include it) whose owner is a super-admin. Free makes posts; the trial is for posting, and the pool gates when posting starts.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Digest","content":{"application/json":{"schema":{"type":"object","properties":{"waiting":{"type":"integer"},"emailWaiting":{"type":"integer"},"oldestWaitingDays":{"type":"integer","nullable":true},"nudgeEveryDays":{"type":"integer"},"dueForNudge":{"type":"integer"},"willNudgeNow":{"type":"integer"},"heldFirst":{"type":"integer"},"openToAll":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"SCOPE_REQUIRED (no `pool:admin`) or SUPER_ADMIN_REQUIRED (the key owner is not a super-admin)"},"429":{"description":"Rate limited"}}},"post":{"tags":["API v2"],"operationId":"v2PoolSendNudges","summary":"Send the due waitlist nudges (at most one per person per nudgeEveryDays, 100 per call)","description":"Needs an API key with the explicit `pool:admin` scope (admin does NOT include it) whose owner is a super-admin. Free makes posts; the trial is for posting, and the pool gates when posting starts. The waitlist-nudger workflow calls this on its schedule.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"Answer without writing anything."}}}}}},"responses":{"200":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"nudged":{"type":"integer"},"due":{"type":"integer"},"dryRun":{"type":"boolean"},"skipped":{"type":"string","nullable":true,"enum":["pool_disabled",null]}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"SCOPE_REQUIRED (no `pool:admin`) or SUPER_ADMIN_REQUIRED (the key owner is not a super-admin)"},"429":{"description":"Rate limited"}}}},"/api/v2/stores/mercatus/connect":{"post":{"tags":["API v2"],"summary":"Connect a Mercatus Liber store","description":"Connects a Mercatus Liber store to a brand from its Store API base URL and a Store API key, exactly as Connect > Store does in the dashboard. The key is proven first (`GET <baseUrl>/store` must answer); nothing is written before that. The key is stored encrypted and is never returned. Calling it again for the same store rotates the key. With `webhooks:manage` among the scopes, flayr also registers its sync webhook (best-effort). The first catalog import is scheduled straight away (best-effort; `importScheduled`). Each connect is recorded in the organization's audit log against the API key. Needs a key with BOTH the `write` scope and the explicit `stores:manage` scope (admin does not include it; the owner grants it in Settings > API keys > Edit scopes). The key owner must be an owner or admin of the brand's organization, and the Mercatus store rollout must be on for the account.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["baseUrl","apiKey"],"properties":{"baseUrl":{"type":"string","description":"The store's https Store API base URL, e.g. https://shop.example.com/api/store/v1."},"apiKey":{"type":"string","writeOnly":true,"description":"The Store API key from the store's admin. Write-only: never echoed back."},"scopes":{"type":"array","items":{"type":"string","enum":["products:read","promotions:read","promotions:write","webhooks:manage"]},"description":"What the store key was granted. Must include products:read. Default [\"products:read\"]."},"brandId":{"type":"string","description":"The brand (GET /api/v2/brands). Required for an account-wide key; a brand-bound key may omit it."}}},"example":{"baseUrl":"https://shop.example.com/api/store/v1","apiKey":"ml_live_…","scopes":["products:read","webhooks:manage"],"brandId":"k17…"}}}},"responses":{"200":{"description":"Connected","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"brandId":{"type":"string"},"storeName":{"type":"string"},"created":{"type":"boolean","description":"false when an existing connection's key was rotated."},"webhookRegistered":{"type":"boolean"},"importScheduled":{"type":"boolean","description":"false when the first import could not be scheduled now; the daily reconcile imports it."}}}}}},"400":{"description":"Bad baseUrl (invalid_base_url), a key that does not look like a key (invalid_key), unknown scopes (invalid_scopes), no brandId on an account-wide key (BRAND_REQUIRED), or the store rejected the key (invalid_key_rejected)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"The plan's connected-account limit is reached (ACCOUNT_LIMIT)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Missing `write` or `stores:manage` (SCOPE_REQUIRED), a brand-bound key naming another brand, the rollout is off, or the owner is not an owner or admin (FORBIDDEN)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"`brandId` is not one of the key owner's brands (BRAND_NOT_FOUND)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"The brand already has a different store (WORKSPACE_ALREADY_CONNECTED), or this store is connected to another brand (SHOP_ALREADY_LINKED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate or quota limit"},"502":{"description":"The store did not answer (store_unreachable) or did not answer as a Store API (bad_response)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"get":{"tags":["API v2"],"summary":"Get the brand's Mercatus store","description":"The brand's connected Mercatus Liber store (URL, name, scopes and import state), or null. Never includes the store key. Needs a key with BOTH the `write` scope and the explicit `stores:manage` scope (admin does not include it; the owner grants it in Settings > API keys > Edit scopes). The key owner must be an owner or admin of the brand's organization, and the Mercatus store rollout must be on for the account.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"The brand (GET /api/v2/brands). Required for an account-wide key; a brand-bound key may omit it."}],"responses":{"200":{"description":"The store","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"store":{"type":"object","nullable":true,"description":"The connected Mercatus store, or null when the brand has none. Never includes the store key.","additionalProperties":true}}}}}},"400":{"description":"No brandId on an account-wide key (BRAND_REQUIRED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing `write` or `stores:manage` (SCOPE_REQUIRED), a brand-bound key naming another brand, the rollout is off, or the owner is not an owner or admin (FORBIDDEN)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"`brandId` is not one of the key owner's brands (BRAND_NOT_FOUND)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate or quota limit"}}},"delete":{"tags":["API v2"],"summary":"Disconnect the brand's Mercatus store","description":"Disconnects the brand's Mercatus Liber store, exactly as \"Disconnect store\" in the dashboard: the connection, its stored key and the imported catalog rows are removed (drafts are kept). Only a Mercatus store: a Shopify App Store connection is refused (NOT_MERCATUS). Recorded in the organization's audit log against the API key. Needs a key with BOTH the `write` scope and the explicit `stores:manage` scope (admin does not include it; the owner grants it in Settings > API keys > Edit scopes). The key owner must be an owner or admin of the brand's organization, and the Mercatus store rollout must be on for the account.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"The brand (GET /api/v2/brands). Required for an account-wide key; a brand-bound key may omit it."}],"responses":{"200":{"description":"Disconnected","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"brandId":{"type":"string"},"deleted":{"type":"object","properties":{"connections":{"type":"integer"},"products":{"type":"integer"},"collections":{"type":"integer"}}}}}}}},"400":{"description":"No brandId on an account-wide key (BRAND_REQUIRED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing `write` or `stores:manage` (SCOPE_REQUIRED), a brand-bound key naming another brand, the rollout is off, or the owner is not an owner or admin (FORBIDDEN)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"`brandId` is not one of the key owner's brands (BRAND_NOT_FOUND), or the brand has no store (NO_CONNECTION)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"The brand's store is not a Mercatus store (NOT_MERCATUS)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate or quota limit"}}}},"/api/v2/stores/mercatus/import":{"post":{"tags":["API v2"],"summary":"Import or refresh the Mercatus store's products","description":"Starts a product import for the brand's Mercatus Liber store, the same as the dashboard's product picker and \"Import now\". With `productGids`, those products are added to the brand's import set and imported (\"submit\"); with none, every product already in the import set is refreshed from the store (\"refresh\"). The import runs in the background: poll GET /api/v2/stores/mercatus/import for `import.running` and the products. The same cooldowns and import-set cap as the dashboard apply. Needs the same key as connect (`write` + explicit `stores:manage`); any member of the brand with store access may import. The brand must have a Mercatus store.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"productGids":{"type":"array","maxItems":300,"items":{"type":"string"},"description":"Products to add and import: `gid://mercatus/Product/<id>` or the bare store product id. Omit to refresh the current import set."},"brandId":{"type":"string","description":"The brand (GET /api/v2/brands). Required for an account-wide key; a brand-bound key may omit it."}}},"example":{"productGids":["gid://mercatus/Product/tee-classic","mug-01"],"brandId":"k17…"}}}},"responses":{"202":{"description":"Import scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"scheduled":{"type":"boolean"},"brandId":{"type":"string"},"mode":{"type":"string","enum":["submit","refresh"]}}}}}},"400":{"description":"A pick that is not a Mercatus product id, collectionGids, more than 300 picks (invalid_selection), or no brandId on an account-wide key (BRAND_REQUIRED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing `write` or `stores:manage` (SCOPE_REQUIRED), a brand-bound key naming another brand, the rollout is off, or the owner is not an owner or admin (FORBIDDEN)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"`brandId` is not one of the key owner's brands (BRAND_NOT_FOUND)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"A refresh with nothing picked yet (no_selection), an import already running (import_in_progress), the store still being prepared (preparing), the import set is full (selection_over_cap), or the brand's store is not a Mercatus store (NOT_MERCATUS)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate or quota limit, or an import ran recently (import_cooldown, with `retryAfterMs` and a Retry-After header)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"get":{"tags":["API v2"],"summary":"List the Mercatus store's imported products","description":"The brand's imported Mercatus products, most recently imported first, one page at a time, plus the import's state (`running`, last run time, status and product count). Needs the same key as connect (`write` + explicit `stores:manage`). The brand must have a Mercatus store.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"The brand (GET /api/v2/brands). Required for an account-wide key; a brand-bound key may omit it."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Products per page."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `nextCursor` of the previous page."}],"responses":{"200":{"description":"Imported products","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"products":{"type":"array","items":{"type":"object","properties":{"productGid":{"type":"string"},"title":{"type":"string"},"handle":{"type":"string"},"status":{"type":"string"},"onlineStoreUrl":{"type":"string","nullable":true},"featuredImageUrl":{"type":"string","nullable":true},"priceRange":{"type":"object","additionalProperties":true},"variantCount":{"type":"integer"},"importedAt":{"type":"number"},"sourceUpdatedAt":{"type":"number","nullable":true}}}},"nextCursor":{"type":"string","nullable":true,"description":"null on the last page."},"import":{"type":"object","properties":{"running":{"type":"boolean"},"lastImportAt":{"type":"number","nullable":true},"lastImportStatus":{"type":"string","nullable":true,"enum":["running","succeeded","failed",null]},"lastImportProductCount":{"type":"integer","nullable":true},"lastImportTruncated":{"type":"boolean"}}}}}}}},"400":{"description":"A bad limit (invalid_limit), or no brandId on an account-wide key (BRAND_REQUIRED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing `write` or `stores:manage` (SCOPE_REQUIRED), a brand-bound key naming another brand, the rollout is off, or the owner is not an owner or admin (FORBIDDEN)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"`brandId` is not one of the key owner's brands (BRAND_NOT_FOUND)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"The brand's store is not a Mercatus store (NOT_MERCATUS)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate or quota limit"}}}},"/api/v2/stores/mercatus/promotions":{"get":{"tags":["API v2"],"summary":"List the Mercatus store's promotions","description":"The promotions (discount codes) in the brand's connected Mercatus Liber store, read live from the store. Needs a key with BOTH `write` and the explicit `stores:manage` scope, and the brand's Mercatus store key must have been granted `promotions:read`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"brandId","in":"query","required":false,"schema":{"type":"string"},"description":"The brand (GET /api/v2/brands). Required for an account-wide key; a brand-bound key may omit it."}],"responses":{"200":{"description":"Promotions","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"promotions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","nullable":true},"kind":{"type":"string","enum":["percentage","fixed"]},"scope":{"type":"string","enum":["cart","product"]},"value":{"type":"number"},"currency":{"type":"string"},"targetSkuIds":{"type":"array","items":{"type":"string"}},"startsAt":{"type":"string","nullable":true},"endsAt":{"type":"string","nullable":true},"usageLimit":{"type":"integer","nullable":true},"redemptionCount":{"type":"integer"},"status":{"type":"string","enum":["active","inactive"]}}}}}}}}},"400":{"description":"A bad field (invalid_field), a bad promotion id (invalid_id), or no brandId on an account-wide key (BRAND_REQUIRED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing `write` or `stores:manage` (SCOPE_REQUIRED), the rollout is off (FORBIDDEN), the store key lacks the promotions scope (store_scope_missing), or the store refused its own key (store_forbidden)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"`brandId` is not one of the key owner's brands (BRAND_NOT_FOUND), or the brand has no store (NO_CONNECTION)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"The brand's store is not a Mercatus store (NOT_MERCATUS) or is not active (store_inactive)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate or quota limit"},"502":{"description":"The store refused the change (store_refused, with its message) or could not be reached (store_unavailable)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"post":{"tags":["API v2"],"summary":"Create a draft promotion in the Mercatus store","description":"Creates a promotion in the brand's Mercatus Liber store. It is ALWAYS created inactive (no shopper can use it); switch it on with PATCH /api/v2/stores/mercatus/promotions/{id} after the merchant approves. Recorded in the organization's audit log against the key. Needs a key with BOTH `write` and the explicit `stores:manage` scope, and the brand's Mercatus store key must have been granted `promotions:write`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","value"],"properties":{"brandId":{"type":"string","description":"The brand. Required for an account-wide key; a brand-bound key may omit it."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"number","description":"percentage: above 0, at most 100. fixed: a whole number of minor units (500 = 5.00)."},"code":{"type":"string","nullable":true,"pattern":"^[A-Za-z0-9_-]{3,40}$","description":"The code shoppers enter; null for none."},"startsAt":{"type":"string","nullable":true},"endsAt":{"type":"string","nullable":true}}}}}},"responses":{"201":{"description":"The new, inactive promotion","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"promotion":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","nullable":true},"kind":{"type":"string","enum":["percentage","fixed"]},"scope":{"type":"string","enum":["cart","product"]},"value":{"type":"number"},"currency":{"type":"string"},"targetSkuIds":{"type":"array","items":{"type":"string"}},"startsAt":{"type":"string","nullable":true},"endsAt":{"type":"string","nullable":true},"usageLimit":{"type":"integer","nullable":true},"redemptionCount":{"type":"integer"},"status":{"type":"string","enum":["active","inactive"]}}}}}}}},"400":{"description":"A bad field (invalid_field), a bad promotion id (invalid_id), or no brandId on an account-wide key (BRAND_REQUIRED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing `write` or `stores:manage` (SCOPE_REQUIRED), the rollout is off (FORBIDDEN), the store key lacks the promotions scope (store_scope_missing), or the store refused its own key (store_forbidden)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"`brandId` is not one of the key owner's brands (BRAND_NOT_FOUND), or the brand has no store (NO_CONNECTION)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"The brand's store is not a Mercatus store (NOT_MERCATUS) or is not active (store_inactive)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate or quota limit"},"502":{"description":"The store refused the change (store_refused, with its message) or could not be reached (store_unavailable)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/v2/stores/mercatus/promotions/{id}":{"patch":{"tags":["API v2"],"summary":"Switch a Mercatus store promotion on or off","description":"Sets the promotion's status. \"active\" makes it live for shoppers; confirm with the merchant first. Nothing else can be edited here. Recorded in the organization's audit log against the key. Needs a key with BOTH `write` and the explicit `stores:manage` scope, and the brand's Mercatus store key must have been granted `promotions:write`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The promotion id from the list or the create."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"brandId":{"type":"string","description":"The brand. Required for an account-wide key; a brand-bound key may omit it."},"status":{"type":"string","enum":["active","inactive"]}}}}}},"responses":{"200":{"description":"The promotion with its new status","content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"promotion":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","nullable":true},"kind":{"type":"string","enum":["percentage","fixed"]},"scope":{"type":"string","enum":["cart","product"]},"value":{"type":"number"},"currency":{"type":"string"},"targetSkuIds":{"type":"array","items":{"type":"string"}},"startsAt":{"type":"string","nullable":true},"endsAt":{"type":"string","nullable":true},"usageLimit":{"type":"integer","nullable":true},"redemptionCount":{"type":"integer"},"status":{"type":"string","enum":["active","inactive"]}}}}}}}},"400":{"description":"A bad field (invalid_field), a bad promotion id (invalid_id), or no brandId on an account-wide key (BRAND_REQUIRED)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Missing `write` or `stores:manage` (SCOPE_REQUIRED), the rollout is off (FORBIDDEN), the store key lacks the promotions scope (store_scope_missing), or the store refused its own key (store_forbidden)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"`brandId` is not one of the key owner's brands (BRAND_NOT_FOUND), or the brand has no store (NO_CONNECTION)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"The brand's store is not a Mercatus store (NOT_MERCATUS) or is not active (store_inactive)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate or quota limit"},"502":{"description":"The store refused the change (store_refused, with its message) or could not be reached (store_unavailable)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` --- Source: https://flayr.social/docs/ai-assistants # Flayr AI assistants Start at https://flayr.social/ai-setup. Over MCP, connecting, reading, drafting and publishing need the Pro plan or higher. REST API keys: reading from Pro+, AI generation from Pro+, publishing from Agency+. Queues and approvals need Agency+. Generation uses the plan's Embers; your assistant subscription is separate. The full MCP server is /api/mcp; Claude and ChatGPT toolsets are /api/mcp/claude and /api/mcp/chatgpt. Use OAuth or an API key. The separate native AI Connection at /api/connectors/mcp uses OAuth with an operator-registered client. It reads workspace/brand/destination/content data, creates and revises text drafts, and prepares publishing for explicit confirmation in Flayr. Native capabilities depend on the registered client and granted operations; do not assume the full MCP tool list applies to that connection. Contact hello@flayr.social for native client registration. Read grants inspection; write grants draft editing; publish grants posting and scheduling. Select only the brands and permissions you need. Revoke connections in Settings → Integrations. Revocation does not delete saved content or copies already returned to your assistant. The assistant provider processes returned content under its own policy. ## Automation recipes (n8n, Zapier, Make) ```json { "mcpUrl": "https://flayr.social/api/mcp", "pingUrl": "https://flayr.social/api/v2/ping", "contentUrl": "https://flayr.social/api/v2/content", "authHeaderName": "Authorization", "authHeaderValue": "Bearer flayr_sk_YOUR_KEY", "draftBody": "{\"text\":\"Hello from my automation\"}", "plans": { "apiKeys": "Pro", "restPublish": "Agency" }, "curl": { "ping": "curl -s https://flayr.social/api/v2/ping -H \"Authorization: Bearer flayr_sk_YOUR_KEY\"", "draft": "curl -s -X POST https://flayr.social/api/v2/content -H \"Authorization: Bearer flayr_sk_YOUR_KEY\" -H \"Content-Type: application/json\" -d '{\"text\":\"Hello from my automation\"}'", "mcpInitialize": "curl -s -X POST https://flayr.social/api/mcp -H \"Content-Type: application/json\" -H \"Accept: application/json, text/event-stream\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"check\",\"version\":\"1.0.0\"}}}'" }, "expected": { "ping": "{\"ok\":true,\"authenticated\":true,\"userId\":\"<your user id>\",\"tier\":\"<your plan>\",\"brandId\":null,\"brandName\":null,\"ts\":<time>}", "draft": "{\"id\":\"<draft id>\",\"status\":\"draft\",\"brandId\":\"<your brand id>\"}", "mcpInitialize": "\"serverInfo\":{\"name\":\"flayr\"" }, "checks": { "key": { "how": "Run this in a terminal with your new key.", "call": { "label": "Check the key", "code": "curl -s https://flayr.social/api/v2/ping -H \"Authorization: Bearer flayr_sk_YOUR_KEY\"" }, "expected": { "label": "A working key answers", "code": "{\"ok\":true,\"authenticated\":true,\"userId\":\"<your user id>\",\"tier\":\"<your plan>\",\"brandId\":null,\"brandName\":null,\"ts\":<time>}" } }, "mcpUrl": { "how": "The server answers this without a key, so it shows the URL is right.", "call": { "label": "Check the MCP URL", "code": "curl -s -X POST https://flayr.social/api/mcp -H \"Content-Type: application/json\" -H \"Accept: application/json, text/event-stream\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"check\",\"version\":\"1.0.0\"}}}'" }, "expected": { "label": "The answer contains", "code": "\"serverInfo\":{\"name\":\"flayr\"" } } }, "frameworks": [ { "id": "n8n", "name": "n8n", "step": "HTTP Request node", "docsUrl": "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/", "auth": { "steps": [ "Add an HTTP Request node to your workflow.", "Set Authentication to Generic Credential Type, choose Header Auth, and create a new credential with the Name and Value below." ], "fields": [ { "field": "Header Auth, Name", "value": "Authorization" }, { "field": "Header Auth, Value", "value": "Bearer flayr_sk_YOUR_KEY" } ] }, "check": { "steps": [ "Set Method to GET and paste the URL below.", "Run the node (Execute step)." ], "fields": [ { "field": "URL", "value": "https://flayr.social/api/v2/ping" } ] }, "draft": { "steps": [ "Set Method to POST and paste the URL below.", "Turn on Send Body. Set Body Content Type to JSON and Specify Body to Using JSON, then paste the JSON below.", "Run the node. Or skip the fields: choose Import cURL and paste the curl command from \"REST with an API key\" above." ], "fields": [ { "field": "URL", "value": "https://flayr.social/api/v2/content" }, { "field": "JSON", "value": "{\"text\":\"Hello from my automation\"}" } ] } }, { "id": "zapier", "name": "Zapier", "step": "Webhooks by Zapier", "docsUrl": "https://help.zapier.com/hc/en-us/articles/8496326446989", "note": "Webhooks by Zapier is a Zapier premium app: it needs a paid Zapier plan.", "auth": { "steps": [ "Add an action step to your Zap and choose Webhooks by Zapier.", "In every Webhooks step you add, fill Headers with the name on the left and the value on the right." ], "fields": [ { "field": "Headers, left box", "value": "Authorization" }, { "field": "Headers, right box", "value": "Bearer flayr_sk_YOUR_KEY" } ] }, "check": { "steps": [ "Choose the event GET and paste the URL below.", "Test the step." ], "fields": [ { "field": "URL", "value": "https://flayr.social/api/v2/ping" } ] }, "draft": { "steps": [ "Choose the event POST and paste the URL below.", "Set Payload Type to json. Under Data, put text on the left and your post text on the right (type it, or map it from an earlier step).", "Test the step." ], "fields": [ { "field": "URL", "value": "https://flayr.social/api/v2/content" }, { "field": "Data, left box", "value": "text" }, { "field": "Data, right box", "value": "Hello from my automation" } ] } }, { "id": "make", "name": "Make", "step": "HTTP, Make a request", "docsUrl": "https://apps.make.com/http", "auth": { "steps": [ "Add the HTTP app to your scenario and choose the module Make a request.", "Set Authentication type to API key and add new Credentials with the values below. Set API key placement to In the header." ], "fields": [ { "field": "Key", "value": "Bearer flayr_sk_YOUR_KEY" }, { "field": "API key parameter name", "value": "Authorization" } ] }, "check": { "steps": [ "Paste the URL below, set Method to GET and Parse response to Yes.", "Choose Run once." ], "fields": [ { "field": "URL", "value": "https://flayr.social/api/v2/ping" } ] }, "draft": { "steps": [ "Paste the URL below and set Method to POST.", "Set Body content type to application/JSON and Body input method to JSON string, then paste the JSON below into Body content.", "Set Parse response to Yes and choose Run once." ], "fields": [ { "field": "URL", "value": "https://flayr.social/api/v2/content" }, { "field": "Body content", "value": "{\"text\":\"Hello from my automation\"}" } ] } } ] } ``` ## Complete full-server MCP tool list ### media_qa_get Reads the cached video/audio QA report, timestamped findings and approval/booking gate. Missing or failed QA blocks. API keys cannot override. Kind: read. Scope: read. Endpoint: GET /api/v2/content/{id}/qa. ### media_qa_rerun Queues a free media QA run using the existing per-minute cap. Poll media_qa_get. Does not approve, book or override. Kind: write. Scope: write. Endpoint: POST /api/v2/content/{id}/qa/rerun. ### whoami Returns who this connection (an OAuth sign-in or an API key) belongs to: userId, the account's current plan tier, and brandId/brandName when the connection is bound to one brand (null = account-wide). Call this first to learn what the connection can reach. Kind: read. Scope: read. Endpoint: GET /api/v2/ping. ### invite_brand_viewer Invites an external client to view one brand (client project), without joining the agency organization or seeing sibling brands. Use an id from list_brands and the client email. The connection needs write scope and its owner must be an org owner/admin. Only role viewer is supported; this does not grant approval, edit, publish or billing access. The invite expires after seven days. A pending duplicate is refused. success means the invite was created; check emailSent separately and relay a false value to the user. Kind: write. Scope: write. Endpoint: POST /api/v2/brands/{id}/invites. ### list_brands Lists the brands this connection can file content into and publish through. Use an `id` as `brandId` on create_content, publish, queues and analytics tools; "personal" means the account owner's personal accounts. A connection bound to one brand sees only that brand (and personal is null). Each brand has its `website` and a `setup` checklist (hasBrandKey, hasWebsite, hasCtaGoal, adsConnected): set a missing website with brand_profile_update; add a brand with create_brand (account-wide connections only); a brand API key is created by the owner in Settings, never by an agent. Kind: read. Scope: read. Endpoint: GET /api/v2/brands. ### create_brand Creates a new brand in the account owner's organization, the same as "New brand" in the dashboard. Send `name` and optionally `website`, like `{ name: "Dragon Shop", website: "https://shop.example.com" }`. Only an ACCOUNT-WIDE connection with the write scope can do this; a connection bound to one brand gets 403. The plan's brand limit applies: at the limit the call is a 402 and nothing is created (relay the message). Optional `profile`, `voice`, `colors` and `fonts` (the brand_profile_update shapes) and `logoStorageId` (an image from upload_media) are saved in the same call. Pass `orgId` only when a 422 with code ORG_REQUIRED lists more than one organization. Creates a brand, never an API key; every create is audited against this connection. Kind: write. Scope: write. Endpoint: POST /api/v2/brands. ### brand_profile_get A brand's profile (website, companyName, tagline, industry, audience, values, pillars, hashtag sets), its default voice, colors and fonts. `brandId` comes from list_brands; a brand-bound connection may omit it. Kind: read. Scope: read. Endpoint: GET /api/v2/brand/intelligence. ### brand_profile_update Fills in a brand's profile — e.g. `{ brandId, profile: { website: "https://…" } }`. Changes only the fields you send; the voice, colors and fonts stay as they are unless you pass them. Use it to clear list_brands setup items such as hasWebsite. Owners, admins and editors only; every change is audited against this connection. Kind: write. Scope: write. Endpoint: PATCH /api/v2/brand/intelligence. ### list_connected_accounts The social accounts a brand can post to — the same set publish would use for that `brandId`: platform, handle, display name, health (healthy, needs_reauth, disconnected), whether it is the brand's default for its platform (`isDefault`) and whether flayr can post there right now (`postable`; Reddit is paused because Reddit closed its API to third-party apps). Call this before publish to pick platforms; for an account that is not healthy, account_reconnect returns the link the user opens to reconnect it. Kind: read. Scope: read. Endpoint: GET /api/v2/accounts. ### account_refresh Re-reads a connected account's handle, display name and avatar from the network (use after the user renames the account) and returns the stored values. Changes nothing else: no connect, disconnect or post. If the status is not `updated`, tell the user to reconnect the account at the returned `reconnectUrl`. Kind: write. Scope: write. Endpoint: POST /api/v2/accounts/{id}/refresh. ### account_remove DESTRUCTIVE: removes ONE dead connection (by account id) from the brand, leaving the brand's other accounts on that platform alone. Call it with dryRun=true first and show the user the result. It never cancels anything: if posts, review holds, queue items or shares are still on the account it refuses with the counts (409); a healthy connected account is refused too (the user disconnects it on the Connect page). Confirm with the user first. Kind: destructive. Scope: write. Endpoint: DELETE /api/v2/accounts/{id}. ### account_reconnect Returns `authUrl`, the link the user opens (signed in to flayr, with this brand selected) to re-authorise an account that list_connected_accounts shows as needs_reauth or disconnected. It connects and disconnects nothing itself. Scheduled posts and the brand's default destination stay on the account. Give the user the link; do not open it for them. A shared-in account is reconnected in the brand that owns it (409). Kind: write. Scope: write. Endpoint: POST /api/v2/accounts/{id}/reconnect. ### account_set_default Sets the brand's default account for one platform (where posts on that platform go when no account is named), or clears it with accountId null. Only the brand's owners and admins can change it, and the account must be one list_connected_accounts shows for that platform. Confirm the account with the user first. Kind: write. Scope: write. Endpoint: PUT /api/v2/accounts/defaults. ### get_dm_entry_points What a connected Instagram account or Facebook Page (id from list_connected_accounts) shows when someone opens a DM: ice breaker questions, and on Facebook also the greeting, Get Started button and menu links. `config` lists the suggested questions, link kinds and limits. Kind: read. Scope: read. Endpoint: GET /api/v2/accounts/{id}/entry-points. ### set_dm_entry_points Changes what EVERY visitor sees when they open a DM with the account; only the fields you pass change, null or [] removes one. Instagram takes iceBreakers only (question text, up to 4); a Facebook Page also takes greeting, menuLinks ({title, https url}) and getStarted. If `foreignPayloads` from get_dm_entry_points is not empty, setting iceBreakers replaces entry points made outside flayr: say so. Show the user the exact text and confirm before calling. Kind: publish. Scope: publish. Endpoint: PUT /api/v2/accounts/{id}/entry-points. ### clear_dm_entry_points DESTRUCTIVE: removes the ice breakers, and on Facebook also the greeting, menu and Get Started button, from the account; every visitor stops seeing them. Confirm with the user first. Kind: destructive. Scope: publish. Endpoint: DELETE /api/v2/accounts/{id}/entry-points. ### list_youtube_playlists Playlists of the YouTube channel(s) a brand publishes to. Use a playlist id as `youtube.playlistId` on create_content or publish. Kind: read. Scope: read. Endpoint: GET /api/v2/youtube/playlists. ### list_pinterest_boards Boards of the Pinterest account(s) a brand publishes to. Use a board id as `pinterest.boardId` on publish. A board is required; the one you pick is remembered as the brand's default for next time, and a publish that uses the default says so (defaultBoardApplied). Kind: read. Scope: read. Endpoint: GET /api/v2/pinterest/boards. ### suggest_tags Hashtag and @mention suggestions for each platform, from the brand's own config: hashtags from its brand profile's hashtag sets (within each platform's limit, skipping ones already in `text`), mentions from its mention contacts written the way each network receives them (`@handle`; on LinkedIn `@[Name](urn:li:organization:…)`). A contact with no account on a platform is not suggested there. Suggestions only: nothing is added to any caption; offer them to the user. Instagram allows 30 hashtags and YouTube 15; publish removes extra ones. Kind: read. Scope: read. Endpoint: POST /api/v2/content/suggest-tags. ### upload_media Step 1 of attaching a LOCAL file (video, image or audio) to a draft. Returns a single-use, short-lived `uploadUrl`. Step 2: POST the raw file bytes to it with the file's Content-Type, e.g. `curl -X POST -H "Content-Type: video/mp4" --data-binary @clip.mp4 "<uploadUrl>"` — the JSON response has a `storageId`. Step 3: pass it as `videoStorageId` or `imageStorageId` on create_content or update_content. For music-library audio, pass storageId to music_tracks_create instead. For media already on the web, skip this and pass `videoUrl` / `imageUrl` instead. Returns 413 when the account's storage is full. Kind: write. Scope: write. Endpoint: POST /api/v2/media/upload-url. ### list_content Lists content items (drafts), newest first, one page at a time: each item is a summary (id, title, type, durationMs, createdAt, postState "posted" / "scheduled" / null). Page with `limit` and `cursor` (the previous page's nextCursor). Call get_content with an id for the full item: caption, media, per-platform text and where it went out. Kind: read. Scope: read. Endpoint: GET /api/v2/content. ### get_content One content item plus its live posting status: `postState` and `posts[]` (up to 20, newest first) with each post's status (scheduled · publishing · published · partial · failed · review_held · held), scheduledAt, and per-platform status, live URL and error. The item's own `status` stays "draft" after publishing — read `posts` to know whether it is live. Use this to confirm a publish landed. Kind: read. Scope: read. Endpoint: GET /api/v2/content/{id}. ### create_content Creates a DRAFT content item. Nothing is posted. Give `text` plus optional media (`videoUrl` / `imageUrl`, or `videoStorageId` / `imageStorageId` from upload_media), target `platforms`, `brandId` (from list_brands; omitted → the brand last active in the dashboard; required once the account is in more than one organization), per-platform captions (`platformText`), creator `credits`, `labels` and YouTube options. Returns the new `id` — pass it as `contentId` to publish or add_queue_items. Kind: write. Scope: write. Endpoint: POST /api/v2/content. ### edit_post_labels Sets internal post labels and per-platform/account instanceLabels. Omitted sets stay unchanged; [] clears a set; labelMode set replaces both sets, add appends atomically. Use get_post to list both. Works after booking and publishing, and never contacts social networks. Labels are key:value (campaign, experiment, variant, repost, series, source-run, or free keys). Needs publish scope and the publishing plan. Kind: write. Scope: publish. Endpoint: PATCH /api/v2/posts/{id}. ### update_content Edits a draft in place; only the fields you pass change. Any media field replaces the draft's media as a set (keeps the id, so queue items still point at it). Refused (409) for archived or already-published items, and a media swap is refused once a queue booked it. `labels`, `opus`, `videoWatermarked`, `library` and `aiGenerated` may be changed on published items too. `aiGenerated` is the post's AI label: false for real footage, null back to automatic. A video draft's custom thumbnail/cover: `thumbnailStorageId` (an image from upload_media) or `thumbnailUrl`, or `thumbnailFrameOffsetMs` for a frame of the video; `thumbnailUrl: null` clears it. It is sent to YouTube (long-form), Facebook, LinkedIn, Instagram Reels, TikTok and Pinterest at publish. Kind: write. Scope: write. Endpoint: PATCH /api/v2/content/{id}. ### labels_bulk_edit Adds and/or removes labels on up to 100 content items in one call: each item becomes (labels − remove) + add. Published items are fine (labels are metadata). Each item succeeds or fails on its own; read `results`. Removing `source:ai-generated` does not turn a post's AI label off: with no explicit toggle it follows how the media was made, and the result carries a `warning`. For real footage also call update_content with `aiGenerated: false` on each item. Kind: write. Scope: write. Endpoint: POST /api/v2/content/labels. ### archive_content Soft-archives an uncommitted draft or failed generation. Keeps its content and media; Restore is available in the Library Archive view. Repeating the call is safe. Refused (409) for ready, staged, scheduled or published content, or any posting queue, post or approval history. Needs write scope and the same owner/admin authority as Library archive. A brand-bound connection only reaches its own brand. Kind: write. Scope: write. Endpoint: POST /api/v2/content/{id}/archive. ### delete_content DESTRUCTIVE: permanently deletes a content item from the library. Posts already live on a platform are not removed. Needs the `write` scope. Ask the user before calling. Kind: destructive. Scope: write. Endpoint: DELETE /api/v2/content/{id}. ### combine_clips Extends a video draft (`id`) with more clips and image cards into ONE finished video, rendered by flayr and saved as a NEW linked draft (same brand, caption copied, credits merged, labelled variant:combined). Nothing is posted and the original is unchanged. Use it to show a finished print with painting/assembly clips before or after it. `segments` (2-8, in order) must include the video itself as { kind: "clip", contentId: id }; clips are Library videos (contentId) or uploads (storageId from upload_media) with inMs/outMs (or durationMs = the clip's full length); cards are images (contentId of a Library image or video thumbnail, or imageStorageId) with durationMs and optional text. `transition` cut|crossfade, `audio` keep|mute_extras|main_across. Max 60 min by default (long-form: cold open + trimmed recording + bumpers). Costs 25 Embers per started minute of output for the first 3 min, then 5 per further started minute by default (refunded on failure). Returns a jobId — poll get_job_status. Kind: write. Scope: write. Endpoint: POST /api/v2/content/{id}/combine. ### list_studio_cuts Saved versions (drafts and final cuts) of a Long-form Studio project (`id`), newest first, and THE final cut: the one campaigns and approvals use, with its rendered draft (`contentId`). Pass `diff` (a cut id, or empty for the board as it stands) to also get what it changed since the auto cut. Free. Kind: read. Scope: read. Endpoint: GET /api/v2/video-studio/projects/{id}/cuts. ### save_studio_cut `action: "save_draft"` stores the edit as it stands as a named version; free, nothing renders. `action: "save_final"` with `quoteId` (an accepted render quote: plan the project, then quote step `render`, estimate first) stores it and renders it; once ready it becomes the final cut, one at a time, and earlier versions are kept. `action: "reopen"` with `cutId` puts a saved version back on the board; the next save is a new version. Kind: write. Scope: write. Endpoint: POST /api/v2/video-studio/projects/{id}/cuts. ### get_job_status Status of an async job (combine_clips, render_motion_ad, or an API video generation): pending, processing, completed or failed. For a combine or a motion ad, `resultContentId` is the new draft once completed; a failed combine is refunded automatically. Poll every 10-30 s — renders take about a minute. Kind: read. Scope: read. Endpoint: GET /api/v2/generate/status/{jobId}. ### render_motion_ad Turns one Library image (the card) into a 6-15 s motion ad: hook (push-in on the card), up to 3 body beats (pans with the text), then a CTA end card in the brand color with the CTA and the link host. 9:16 unless `aspect` is 1:1 or 16:9. The text is used exactly as given; it is not rewritten. Saves a new draft in the card's brand (labels format:motion-ad, source:template); nothing is posted and the card is unchanged. Free. Returns a jobId: poll get_job_status. Kind: write. Scope: write. Endpoint: POST /api/v2/video-studio/templates/motion-ad-from-card/render. ### list_brand_segments A brand's segments: one per confirmed offer that names an audience, with its pains, outcomes, proof and the brand website (the default CTA link), ranked shops/commerce first and local services second (each has `tier` and `rank`). Read-only, free. Pass the segment `id` to generate_segment_ad. Kind: read. Scope: read. Endpoint: GET /api/v2/video-studio/segment-ads. ### generate_segment_ad Builds a segment's ad script as beats (hook, persona, offer, proof, CTA) from the owner's own words, or checks the `beats` you edited. Every beat is claims-checked and any figure must come from the segment's offer, outcomes or proof (nothing is invented). Without `render` it returns { segment, script, issues, claims, variants } and stores nothing. `variants` are per-network proposals (TikTok, X, Pinterest, Reddit by default, or `networks`): the ad text cut to that network's cap from whole beats, the planned length and the ad-cut lint of the planned cut, with `ready`. Proposals only: nothing is booked or spent. With `render: true`, `contentId` (a Library card of the same brand) and a clean script it queues a free, silent 9:16 motion ad and returns a jobId. Saves a draft; nothing is posted. Voice it with voice_segment_ad. Kind: write. Scope: write. Endpoint: POST /api/v2/video-studio/segment-ads. ### voice_segment_ad Speaks a segment ad's script over the silent draft generate_segment_ad rendered (`contentId` = its resultContentId; pass the same `segmentId` and edited `beats`). Voice: `{ kind: "stock", stockVoiceId }` (default openai/tts-1:onyx) or the owner's `{ kind: "clone", cloneId }`; the brand pronunciation list is applied. No captions are added (the ad already shows each beat). A script too long for the ad is refused with speech_too_long (the voice is never sped up): shorten a beat. Costs the usual voiceover Embers (charged when queued, refunded on failure). Saves a new voiced draft; nothing is posted. Kind: write. Scope: write. Endpoint: POST /api/v2/video-studio/segment-ads/voice. ### plan_teardown Teardown Studio: send a 3D model (`model`, base64 STL, 3MF or GLB, up to 3 MB inline) and get its parts list, a default teardown/1 plan (hold, explode, label the biggest parts, slow-motion, reassemble, reveal, brand end card; 16:9 and 9:16) built from part count and bounding boxes, and the render estimate (frames, worker time; free). Rename parts with `names` ({ p0: "Lid" }). Or send an edited `plan` instead of a model to check it against the limits and re-estimate. Nothing is stored, rendered or charged. A model that is not a physical object (status render or prototype) is labelled "3D render" in the film. Kind: read. Scope: read. Endpoint: POST /api/v2/video-studio/templates/teardown/plan. ### ad_cut_lint Checks an ad's cut against the ad-cut rules: too many joins (warning), joins only at a rest point, no cut inside a caption or its fade, one caption layer, no audio dip at a join, exactly one ending, and the network's length / aspect / ad-text window (TikTok 9:16, 12-25 s, ad text up to 100 by default). Each finding names its fix. It reads the cut you describe (segments, captions, signals), not a rendered file; a rule with nothing to check is reported unchecked. With contentId the result is kept for that draft: a format:ad video draft is booked or filed as an ad only once its latest lint for the network passes. Kind: write. Scope: write. Endpoint: POST /api/v2/video-studio/ad-cut/lint. ### video_studio_auto_run Long-form Video Studio project `id`: with no `action` it runs the brand's enabled auto steps (dead-air trims at sentence boundaries, retake picks, dissolves, room tone, loudness, presets) and writes suggestion items for the timeline. Suggestions only: the master is never touched and nothing renders. Then `action` accept / remove / swap with a `suggestionId` (from video_studio_auto_suggestions) decides one: accept writes the board decision (undoable), swap picks another `transitionId`/`ms` or `presetId`. Free. Kind: write. Scope: write. Endpoint: POST /api/v2/video-studio/projects/{id}/auto. ### video_studio_auto_suggestions The auto-edit suggestions for Video Studio project `id` (step, kind, status, where on the timeline, a plain summary, the payload), the latest run (which steps ran or were skipped and why) and the brand's auto profile. Free. Kind: read. Scope: read. Endpoint: GET /api/v2/video-studio/projects/{id}/auto. ### publish PUBLISHES TO REAL SOCIAL ACCOUNTS. Posts now, or at `scheduledAt` (ISO-8601, future). Prefer `contentId` (a draft from create_content: its text and media become the post) over inline `content`. The post goes out through the target brand's own connected accounts. Always pass an `idempotencyKey` so a retry never double-posts. `platformText` ({ twitter: "…", linkedin: "…" }) gives each platform its own caption, as update_scheduled_post takes it (saved on the draft with contentId); unknown arguments are refused (422 unknown_fields). The same safety gates as the dashboard apply: platform readiness/media rules are checked up front (422); if the brand requires scheduled-post review nothing is sent and you get { status: "pending-review", reviewId }; a missing required creator credit in a push-down brand is refused (422 attribution_missing) or held; the "Posted with flayr.social" caption watermark and video watermark follow the plan (409 watermark_pending means the watermarked video is still rendering — retry after retryAfterSeconds); 409 duplicate_content means the same content already went to that account in the last 24 hours (existingPostId names it; nothing new was posted). `facebook: { contentType: "reel" }` posts a Facebook Reel (exactly one video), `"story"` a Story, `"feed"` a regular post; `instagram.contentType` works the same; omitted → the draft's saved post type. `instagram.trialReel: { enabled: true, graduation: "manual" | "auto" }` posts a Reel to non-followers first (Instagram Trial Reel; omitted graduation → admin default; ignored with a warning when not a Reel). `pinterest: { boardId, title, link }` picks the board (ids from list_pinterest_boards; required: omitted → the brand's last-picked board for that account, flagged as defaultBoardApplied, else 422 pinterest_board_required), pin title and destination link. `requiresApproval: true` files it for human approval instead of posting. A draft that is already scheduled on one of the platforms is refused (409 already_booked): change the booked post instead, pass `onBooked: "move"` with the new `scheduledAt` to move that booking (a calendar fill must move, never copy), or `allowDuplicateBooking: true` only when the user asked to post it again. Needs the `publish` scope (or admin) and the Pro plan or higher; each publish counts against the plan's direct posts for the month. Confirm with the user before posting now. Then call get_content to see the live URLs. Kind: publish. Scope: publish. Endpoint: POST /api/v2/publish. ### get_post A post (`id` = convexPostId from publish, or posts[].id from get_content): status, slot, platforms, its internal labels and per-platform/account instanceLabels, and while it is scheduled the first comment each platform will publish and whether it can be changed now. Kind: read. Scope: read. Endpoint: GET /api/v2/posts/{id}. ### update_scheduled_post CHANGES WHAT A SCHEDULED POST WILL PUBLISH on real accounts, keeping its slot, accounts, options, labels and draft. `firstComment` sets per-platform first comments (linkedin, facebook, instagram, threads, youtube; null removes; X/Bluesky have none); `text` / `platformText` change the caption; `applyAutoFirstComment: true` adds the brand's auto first comment where none is set; `removePlatforms` drops platforms from this booking (e.g. a duplicate TikTok); `labels` replaces the post's own labels (e.g. ["repost:evergreen"]; alone it never touches the booking, status "labeled"). Updated in place when the platform scheduler allows it, otherwise re-booked at the same slot (status "rebooked", new postId). Refused within 5 minutes of the slot. Repeating the same edit returns "unchanged". Needs the `publish` scope (or admin) and the Pro plan or higher; each publish counts against the plan's direct posts for the month. Confirm the new text with the user first. Kind: publish. Scope: publish. Endpoint: PATCH /api/v2/posts/{id}. ### reschedule_post MOVES A SCHEDULED POST to `scheduledAt` (ISO 8601 with a timezone, e.g. "2026-11-19T15:00:00Z"; more than 5 minutes ahead). The booking keeps its id, caption, media, accounts and options; its posting-queue slot follows. Returns { status: "rescheduled", scheduledAt }. Refused within 5 minutes of the current slot, while it is posting or posted, and in a brand whose scheduled posts require review. Needs the `publish` scope (or admin) and the Pro plan or higher; each publish counts against the plan's direct posts for the month. Confirm the new time (and its timezone) with the user first. Kind: publish. Scope: publish. Endpoint: PATCH /api/v2/posts/{id}. ### cancel_scheduled_post Takes a SCHEDULED post off the platform schedule and marks it cancelled (the draft stays, so it can be published again). Safe to repeat. Refused within 5 minutes of the slot, and when the platform will not remove it (some YouTube uploads). Needs the `publish` scope (or admin) and the Pro plan or higher; each publish counts against the plan's direct posts for the month. Confirm with the user first. Kind: publish. Scope: publish. Endpoint: DELETE /api/v2/posts/{id}. ### list_reviews Scheduled posts waiting for (or given) a human sign-off, oldest slot first. Page with limit/cursor; filter with slotBefore/slotAfter (ISO), postStatus, status and window. Held/missed exclude cancelled/deleted posts unless includeGone=true. total counts matching reviews per status across all pages. `canApprove` tells whether THIS connection may approve each one. Kind: read. Scope: read. Endpoint: GET /api/v2/reviews. ### decide_review decision "approve" sends a held post to the platform for its slot (GOES LIVE) — needs the explicit `review` scope (admin does not include it) and never works on a post the same connection created. decision "hold" takes a scheduled post off the platform schedule — needs `review` or `publish`. decision "discard" permanently cancels a held or waiting post, including an already-rejected collab, preserving content. Agency plan. `id` is a reviewId or a convexPostId. Kind: publish. Scope: read. Endpoint: POST /api/v2/reviews/{id}. ### bulk_decide_reviews Discard or hold 1–100 scheduled-post reviews in one call. Never approves or publishes. Use dryRun first to list would_discard/would_hold and skipped IDs without changing anything. Discard cancels permanently while keeping content, including already-rejected collabs; hold leaves posts in Held. Needs review or publish on the Agency plan, with the same brand restrictions as individual decisions. Results report partial failures per ID. Kind: destructive. Scope: read. Endpoint: POST /api/v2/reviews/bulk. ### move_reviews Moves one or many posts held for review ("move to Tuesday 10:00", "+1 day"). Moving never approves and nothing goes live. A Held or Missed post (even one booked before it was held) re-opens as pending at the new slot, and a disconnected account it was pinned to is swapped for the brand’s one healthy account on that platform (`accountSwapped`). A post booked at the platform right now answers vendor_booked; use update_scheduled_post. Needs `review` or `publish`. Agency plan. Kind: write. Scope: read. Endpoint: POST /api/v2/reviews/move. ### move_approvals Moves the planned time of one or many items waiting for approval. Moving never approves and books nothing. Needs the explicit `approve` scope (admin does not include it). Agency plan. Kind: write. Scope: read. Endpoint: POST /api/v2/approvals/move. ### switch_post_accounts Re-points platform legs of one post to another healthy connected account of the same brand and platform, e.g. off a disconnected Facebook connection: `switchAccounts` { "facebook": "<accountId>" }. A post HELD for review (pending_review, review_held, missed_review): only flayr's post and its stored review request change; it never approves and the post stays held. `dryRun: true` previews it (status "would_switch"). A SCHEDULED post: the booking at the platform scheduler is changed in place (CHANGES WHAT GOES OUT on a real account; no dryRun). Every switch is audited. Needs the `publish` scope (or admin). Confirm the account with the user first. Kind: publish. Scope: publish. Endpoint: PATCH /api/v2/posts/{id}. ### list_failed The Schedule → Failed backlog of the brand: one row per platform of a post that did not go out, with its row `id`, postId, contentId, account, slot, lastError, reasonClass and `coverage` ("live" / "rebooked" when the platform is now covered elsewhere, null when nothing known covers it). Filters: state (open = what the tab shows, the default), platform, zernioAccountId, reasonClass, slotAfter / slotBefore. Follow `cursor` until it is null; a page can be short. Kind: read. Scope: read. Endpoint: GET /api/v2/failed. ### dismiss_failed Dismisses rows of the Failed backlog by the ids list_failed returned (up to the batch limit per call), like the dashboard's Dismiss. It only closes the row: the post, its status and any live booking are never touched. Each id is decided on its own; one that is not found, another brand's, already closed or being retried is skipped. `dryRun: true` reports what would close. Confirm the count with the user first. Kind: write. Scope: write. Endpoint: POST /api/v2/failed/dismiss. ### approvals_list The approvals inbox: everything that waits on the user's decision, in one list. `kind` "ad_budget" is an ad agent's request above the owner's ceiling (a spend cap, a spending limit, a campaign budget), with `amount`, `changes` and a one-line `summary` of before → after; it shows only with the `approvals:decide` scope, to an owner or admin, and never a request this same connection made. `kind` "manual" or "workflow" is held content (needs `approve` or `approvals:decide`, Agency plan). Read `summary` to the user before deciding anything. Kind: read. Scope: read. Endpoint: GET /api/v2/approvals. ### approvals_decide Decides ONE item from approvals_list (`id`): decision "approve" or "reject", optional `note`. ALWAYS show the user the item's `summary` (e.g. "Monthly ad spend cap: $500.00 → $1,200.00") and get a clear yes before approving. Ad budget requests ("ad_budget") need `approvals:decide`: approving a cap change applies it at once; approving any other request lets the agent repeat its exact call once within 7 days. If the workspace requires money approvals to be restated, the answer is 409 `confirmation_required`: repeat with `confirmAmountMinor` equal to `amountMinor` (null for "remove the limit"), only after the user confirmed that amount. Held content works as in decide_approval (`approve` or `approvals:decide`; a workflow approval may resume a run that publishes). Repeating the same decision is safe (alreadyDecided: true). Every decision is audited with who, when and that it came through MCP. Kind: publish. Scope: approvals:decide. Endpoint: POST /api/v2/approvals/{id}. ### list_approvals Content held for approval that waits on the account owner's decision, newest first: posts filed with publish `requiresApproval: true`, drafts submitted for review, and workflow runs parked at an approval gate. `kind` is "manual" or "workflow". With status "rejected" it lists rejected content instead, with the reviewer's reason (`note`, `reasonChips`), who rejected it and when. Needs the explicit `approve` scope (admin does not include it). Agency plan. Kind: read. Scope: read. Endpoint: GET /api/v2/approvals. ### decide_approval Same rules as the dashboard: the assigned approver, or an owner/admin of the org, may decide. On a "workflow" approval, decision "approve" resumes the parked run, whose next steps may publish (GOES LIVE); "reject" cancels it. On a "manual" approval, "approve" only marks the content approved — nothing is posted until you call publish with its contentId — and "reject" returns it to draft. On "reject", pass the reviewer's reason as `note` (the submitter is told it); it is optional unless the org requires one (then 422 without it). Needs the explicit `approve` scope (admin does not include it). Agency plan. Repeating the same decision is safe (alreadyDecided: true). Confirm with the user before approving a workflow approval. Kind: publish. Scope: read. Endpoint: POST /api/v2/approvals/{id}. ### list_approval_groups The same held content as list_approvals, grouped by piece: the variants of one draft (or sharing a `group:<id>` label), with the axes they vary on (theme, hook, audio …), a tally (approved / redo / dropped / open) and each variant's state and slot time. `status` open (default) / redo / approved / dropped / all. Needs the explicit `approve` scope. Agency plan. Kind: read. Scope: read. Endpoint: GET /api/v2/approval-groups. ### decide_approval_group Decides several variants of a group from list_approval_groups at once, each as decide_approval would: `members` "all" (open variants), an array of approvalIds, or {axis: value} (e.g. {"audio":"voice"}). "approve" marks them approved (a manual approval is NOT posted; a workflow approval resumes its run, which may publish — GOES LIVE); "redo" rejects with the Redo reason; "drop" rejects (`note` = reason). Already-decided variants are skipped. Needs the explicit `approve` scope (admin does not include it). Agency plan. Confirm the count with the user first. Kind: publish. Scope: read. Endpoint: POST /api/v2/approval-groups/{groupId}/decide. ### list_queues Posting (drip) queues of one brand. A queue posts one item every cadenceHours at timeOfDay in its timezone, keeping `lookahead` items booked at the platform. Kind: read. Scope: read. Endpoint: GET /api/v2/queues. ### get_queue A queue and its items in order, with each item's state (queued · publishing · scheduled · posted · failed · skipped), booked or projected slot, and attribution status. Kind: read. Scope: read. Endpoint: GET /api/v2/queues/{id}. ### create_queue Creates a posting queue. Once items are added it BOOKS REAL POSTS on the given platforms on its cadence (default daily 19:00 America/Chicago, 2 booked ahead). Use `startsAt` to hold everything until a date. Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: publish. Scope: publish. Endpoint: POST /api/v2/queues. ### update_queue `status: "paused"` stops new bookings (already-booked posts stay booked); "active" resumes. Other fields (platforms, cadenceHours, timeOfDay, lookahead, startsAt, name) apply from the next booking. Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: publish. Scope: publish. Endpoint: PATCH /api/v2/queues/{id}. ### delete_queue DESTRUCTIVE: deletes the queue (its drafts stay in the library). With posts booked at the platform it is refused (409) unless `unschedule: true`, which first deletes those platform posts. Needs the `publish` scope (or admin) on the Agency plan or higher. Ask the user before calling. Kind: destructive. Scope: publish. Endpoint: DELETE /api/v2/queues/{id}. ### add_queue_items Appends drafts (content ids) to the end of a queue — they will be BOOKED AND POSTED on the queue's schedule. Use `contentIds`, or `items` for per-item YouTube title, platforms, `reviewRequired: true` (holds even on optional/off review brands), and `pinnedAt` (ISO timestamp with offset). Drafts of another brand, duplicates, archived drafts and drafts without a video for a video platform come back in `rejected`. Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: publish. Scope: publish. Endpoint: POST /api/v2/queues/{id}/items. ### queue_item_action `action`: "skip" passes over a queued item; "retry" puts a failed/skipped item back in line; "unschedule" deletes a booked platform post and puts the item back in line. Also `youtubeTitle`, per-item `platforms`, and `position` (0-based among waiting items). Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: publish. Scope: publish. Endpoint: PATCH /api/v2/queues/{id}/items/{itemId}. ### remove_queue_item DESTRUCTIVE: removes an item (the draft stays in the library). A booked (`scheduled`) item is refused (409) unless `unschedule: true`, which deletes its platform post first. Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: destructive. Scope: publish. Endpoint: DELETE /api/v2/queues/{id}/items/{itemId}. ### reorder_queue_items Send every waiting (queued) item id exactly once, in the new order. Booked, posted, failed and skipped items keep their places. Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: publish. Scope: publish. Endpoint: POST /api/v2/queues/{id}/items/reorder. ### get_analytics Engagement overview for the last 7, 30 or 90 days. Pro plan or higher. Kind: read. Scope: read. Endpoint: GET /api/v2/analytics. ### compare_post_instances Per-account metrics and tag, campaign, experiment and series roll-ups. Omit postId for scope-wide roll-ups (up to 100 posts). Include reruns to compare bookings of the same content over time. Historical data stays platform-attributed. Pro plan or higher. Kind: read. Scope: read. Endpoint: GET /api/v2/analytics/instances. ### query_insights Read-only analytics query: one `metric` aggregated (median by default) over posts, broken down by up to a few dimensions (platform, weekday, hour, brand, campaign, postType, label:<key>, arm), at a fixed post age `window` (48h / 7d / 30d / lifetime) so posts are compared fairly. Every row carries its sample size n; platforms that do not report the metric are listed in `availability`, never counted as 0. Pro plan or higher. Kind: read. Scope: read. Endpoint: POST /api/v2/insights/query. ### compare_labels Splits every labelled post by the values of one label key (e.g. key "cut" → cut:opus vs cut:raw) and reports medians with n per group at the 48h / 7d snapshot. Descriptive, not a significance test. Pro plan or higher. Kind: read. Scope: read. Endpoint: GET /api/v2/analytics/experiments. ### list_experiments A/B experiments. Content joins one by carrying the label `experiment:<id>` plus `<compareKey>:<variant>`. Kind: read. Scope: read. Endpoint: GET /api/v2/experiments. ### get_experiment One experiment: hypothesis, variants, compareKey, window and status. Kind: read. Scope: read. Endpoint: GET /api/v2/experiments/{id}. ### create_experiment Creates an A/B experiment. Then tag drafts with its `label` (experiment:<id>) and `<compareKey>:<variant>` via update_content `labels`, publish them, and read get_experiment_results. Kind: write. Scope: write. Endpoint: POST /api/v2/experiments. ### update_experiment Changes an experiment's fields (e.g. status "running" / "done", endAt, notes). Only the fields you pass change. Kind: write. Scope: write. Endpoint: PATCH /api/v2/experiments/{id}. ### delete_experiment DESTRUCTIVE: deletes the experiment record (content keeps its labels). Ask the user before calling. Kind: destructive. Scope: write. Endpoint: DELETE /api/v2/experiments/{id}. ### get_experiment_results The experiment's posts split by its compareKey, with the leading variant by its primary metric and n per arm, plus `overlay`: one line per variant (primary metric to date; align=armDay lines arms up from their first post; null = not reported). Small samples: read medians with their n; name a winner only from get_experiment_readout. Kind: read. Scope: read. Endpoint: GET /api/v2/experiments/{id}/results. ### get_experiment_readout n per arm, pooled reach engagement rate (or average percentage watched when selected), a 90% interval and a hedged verdict (likely_winner, no_clear_winner or not_enough_data). Missing numbers are "not reported" (null), never 0. Say "likely", never "proven". Kind: read. Scope: read. Endpoint: GET /api/v2/experiments/{id}/readout. ### get_experiment_rounds A version test's rounds: each closed round's frozen snapshot, the open round's live numbers (null = not reported), the winner if one was recorded, and any repeat-winner proposal. Kind: read. Scope: read. Endpoint: GET /api/v2/experiments/{id}/rounds. ### start_experiment_round Files the round's versions into the approval queue on the given platforms, in spaced slots with UTM links. Nothing posts until a person approves each one. Round 2 re-tests the arms kept from round 1. Kind: write. Scope: write. Endpoint: POST /api/v2/experiments/{id}/rounds. ### close_experiment_round Freezes the open round's numbers and keeps the best arms for the next round. A winner is recorded only when the readout says likely_winner, or when `pick` names an arm the user chose. Ask the user before passing `pick`. Kind: write. Scope: write. Endpoint: POST /api/v2/experiments/{id}/close-round. ### propose_repeat_winner Proposes slots to post the winning version again (default 3 over 2 weeks). Only a proposal: nothing is booked or posted until the user confirms it in flayr, and then each post still goes through approval. Kind: write. Scope: write. Endpoint: POST /api/v2/experiments/{id}/repeat-winner. ### list_text_templates Reusable text shapes per brand: sections, length targets, hook patterns, CTA slots and guardrails. Use one to shape a draft's text before create_content. Kind: read. Scope: read. Endpoint: GET /api/v2/text-templates. ### get_text_template One format (text template) with its full structure and example. Kind: read. Scope: read. Endpoint: GET /api/v2/text-templates/{id}. ### create_text_template Creates a reusable format (text template) in a brand. Kind: write. Scope: write. Endpoint: POST /api/v2/text-templates. ### update_text_template Changes a format; only the fields you pass change. `archived: true` hides it. Kind: write. Scope: write. Endpoint: PATCH /api/v2/text-templates/{id}. ### delete_text_template DESTRUCTIVE: deletes a format (drafts started from it keep their text). Ask the user before calling. Kind: destructive. Scope: write. Endpoint: DELETE /api/v2/text-templates/{id}. ### list_attribution_rules The brand's "posts like this must carry a credit" rules and its mode (flag / push_down). In push_down mode publish refuses or holds a post missing a required credit — add `credits` with update_content first. Kind: read. Scope: read. Endpoint: GET /api/v2/attribution-rules. ### list_rotations List a brand’s rotation definitions. Supply rotationId to inspect its weekly groups and held reasons. Review with list_approval_groups and decide_approval_group. Kind: read. Scope: read. Endpoint: GET /api/v2/rotations. ### create_rotation Brand admins configure hooks, source media, captions, cadence and networks. Disabled by default. Enabled rotations copy media and file one weekly approval group; only explicit approval books posts. No paid ads or model charges. Kind: publish. Scope: publish. Endpoint: POST /api/v2/rotations. ### update_rotation Patch editable rotation config. Changes apply to the next week; enabled:false pauses generation. Already filed approvals remain for a reviewer to approve or drop. Kind: publish. Scope: publish. Endpoint: PATCH /api/v2/rotations. ### list_share_rules The brand's share rules: "when <account> publishes, reshare to <accounts> (or comment on it) after N minutes with text T", each with its approval mode. Kind: read. Scope: read. Endpoint: GET /api/v2/automations/reshare-rules. ### create_share_rule Creates a rule that reshares (or comments on) every new post of the source accounts. Defaults to needs_approval: each fire waits for approve in act_on_publish_action. Only LinkedIn (native reshare) and X (quote own / retweet) really repost; other platforms get a link share. Confirm with the user first. Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: publish. Scope: publish. Endpoint: POST /api/v2/automations/reshare-rules. ### list_publish_actions Pending, sent and failed comments-after-publish and reshares of the brand (filter by `status`, e.g. needs_approval or failed), with what each waits on. Kind: read. Scope: read. Endpoint: GET /api/v2/automations/actions. ### act_on_publish_action approve lets a rule's reshare / comment go out at its time; retry re-sends a failed one (same idempotency key); reject / cancel stop it. Confirm with the user before approving. Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: publish. Scope: publish. Endpoint: POST /api/v2/automations/actions/{id}. ### add_post_comments Schedules comments on a post, sent once after it is live on that platform and its tokens resolve ({{postUrl}}, {{parentPostUrl:<post id>}}, {{youtubeUrl:<post id>}}), optionally at sendAt. Confirm with the user first. Needs the `publish` scope (or admin) on the Agency plan or higher. Kind: publish. Scope: publish. Endpoint: POST /api/v2/posts/{id}/comments. ### list_post_comments A post's comments-after-publish and reshares, with status (waiting, needs_approval, sent, failed) and the resolved text. Kind: read. Scope: read. Endpoint: GET /api/v2/posts/{id}/comments. ### list_frames The brand's frames (borders, overlays, lower thirds, corner tags, quote-card frames, ribbons) plus the built-in flayr frames in the brand colors. Each has a `ref` to pass to apply_frame. Kind: read. Scope: read. Endpoint: GET /api/v2/frames. ### get_frame One library frame with its sizes and content areas. Kind: read. Scope: read. Endpoint: GET /api/v2/frames/{id}. ### create_frame Copy a flayr frame into the brand library (`defaultKey`, optional colors/texts), or add uploaded PNG/SVG art (upload_media first; `variants` of storageIds, the content area is detected from transparency). Kind: write. Scope: write. Endpoint: POST /api/v2/frames. ### apply_frame Draws a frame over an image and returns a new image URL (the original is untouched). Use the URL in create_content, or pass contentId + platform so that post publishes the framed image on that platform. Free by default; the same inputs again are free. Kind: write. Scope: write. Endpoint: POST /api/v2/frames/apply. ### get_frame_settings Which frame each platform's images get automatically when a post is published or scheduled. Kind: read. Scope: read. Endpoint: GET /api/v2/frames/settings. ### update_frame_settings Frame every image posted to a platform automatically (frameRef), or stop (frameRef null). Applies to posts published or scheduled from now on. Confirm with the user first. Kind: write. Scope: write. Endpoint: POST /api/v2/frames/settings. ### import_frames flayr admins only: load a frame pack into a brand under one batchId (up to 25 frames per call). Kind: write. Scope: write. Endpoint: POST /api/v2/frames/import. ### offers_capture Turns what the brand sells (pasted text, or answers to the offer interview) into draft offers in its offer bank, with prices from the plan catalog, Shopify or the text. Charges Embers once per call (refunded when nothing usable comes back). Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: POST /api/v2/hook-studio/offers. ### offers_list The brand's offer bank (filter by status: draft, confirmed, retired). Free. Needs the Pro plan or higher. Kind: read. Scope: read. Endpoint: GET /api/v2/hook-studio/offers. ### offers_update Edits an offer's fields or status; "confirmed" makes it usable for hooks and CTAs. Confirm changes with the person first. Free. Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: PATCH /api/v2/hook-studio/offers. ### hooks_generate Writes a batch of draft hooks (on-screen card + spoken line) from the confirmed offers, claims-checked; blocked ones come back in `dropped`, unsaved. Charges Embers once per call (refunded when nothing usable comes back). Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: POST /api/v2/hook-studio/hooks/generate. ### hooks_list The brand's hook bank (filter by status: draft, approved, retired), with each hook's claims result. Free. Needs the Pro plan or higher. Kind: read. Scope: read. Endpoint: GET /api/v2/hook-studio/hooks. ### hooks_update Edits a hook or sets its status. New copy is claims-checked again; a hook whose claims block cannot be approved. Free. Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: PATCH /api/v2/hook-studio/hooks. ### bodies_map Maps library clips, Shopify products, features or texts to draft bodies (what each shows and proves) so hooks can lead into them. Charges Embers once per call (refunded when nothing usable comes back). Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: POST /api/v2/hook-studio/bodies/map. ### ctas_generate Writes a batch of draft calls to action for the confirmed offers, claims-checked against where they point. Charges Embers once per call (refunded when nothing usable comes back). Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: POST /api/v2/hook-studio/ctas/generate. ### ctas_list The brand's CTA bank (filter by status: draft, approved, retired), with each CTA's goal (goalKey, isPrimary, paidEligible, adButton) and claims result. Free. Needs the Pro plan or higher. Kind: read. Scope: read. Endpoint: GET /api/v2/hook-studio/ctas. ### ctas_create Adds a call to action written by the person, claims-checked, optionally tagged as a goal (goalKey; isPrimary makes it the brand's primary goal and demotes the previous one). Nothing here creates or runs an ad. Free. Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: POST /api/v2/hook-studio/ctas. ### ctas_update Edits a CTA, its status or its goal fields (goalKey, isPrimary, paidEligible, adButton). New copy or a new destination is claims-checked again; a CTA whose claims block cannot be approved. Free. Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: PATCH /api/v2/hook-studio/ctas. ### cta_settings_get The brand's goals (source tagged, implicit from the website, or none; the primary goal) and its CTA check settings (ctaLevel, ctaPaidLevel, organicSupportingHosts, autoApplyPrimaryCta). Free. Needs the Pro plan or higher. Kind: read. Scope: read. Endpoint: GET /api/v2/hook-studio/cta-settings. ### cta_settings_update Changes only the CTA check settings sent: ctaLevel (off, warn, block), ctaPaidLevel (warn or block), organicSupportingHosts and autoApplyPrimaryCta. Only the brand's owners and admins can change them. Confirm changes with the person first. Free. Needs the Pro plan or higher. Kind: write. Scope: write. Endpoint: PATCH /api/v2/hook-studio/cta-settings. ### claims_check Checks a hook, CTA, caption or ad against the brand's claims sources (verified prices, banned phrases, competitors, destinations). No model call, nothing stored, free. Needs the Pro plan or higher. Kind: read. Scope: read. Endpoint: POST /api/v2/hook-studio/claims/check. ### cta_check Checks whether a draft, post or link points at the brand's goal page (the same check the ad and boost routes run in paid mode; a block there refuses the ad). Run it before every boost or ad and paste the result. Nothing stored, free. Needs the Pro plan or higher. Kind: read. Scope: read. Endpoint: POST /api/v2/cta-check. ### get_signup_sources Sign-ups, first posts and paid conversions per sign-up source (paid:<network>, organic, outreach, friends_family, internal, unknown), with the total net of friends/outreach/internal, and per ad campaign, ad content, ad set (utm_term) and landing path, including the campaign x landing grid (optional campaign prefix filter, e.g. fl-w1-). Counts only, no identities. Every brand except the owner brand gets 403. Kind: read. Scope: read. Endpoint: GET /api/v2/analytics/signup-sources. ### list_growth_triggers The brand's keyword triggers: a comment matching a keyword gets a public reply and/or a DM. Shows whether each is active and its counts. Kind: read. Scope: read. Endpoint: GET /api/v2/growth-triggers. ### get_growth_trigger One trigger with its keywords, texts, link, cap and counts. Kind: read. Scope: read. Endpoint: GET /api/v2/growth-triggers/{id}. ### get_growth_trigger_stats Matched comments, unique commenters, replies, DMs and failures, in total and per day. Kind: read. Scope: read. Endpoint: GET /api/v2/growth-triggers/{id}/stats. ### create_growth_trigger Creates a keyword trigger, always INACTIVE: nothing is sent until a person turns it on. DMs work on Instagram and Facebook only; the reply text must not contain a keyword. Kind: write. Scope: write. Endpoint: POST /api/v2/growth-triggers. ### update_growth_trigger Changes a trigger; only the fields you pass change. `active: true` makes it reply to and DM real people from then on and needs the publish scope: confirm with the user first. `active: false` pauses it. Kind: publish. Scope: write. Endpoint: PATCH /api/v2/growth-triggers/{id}. ### delete_growth_trigger DESTRUCTIVE: deletes a trigger (its logs stay). Ask the user before calling. Kind: destructive. Scope: write. Endpoint: DELETE /api/v2/growth-triggers/{id}. ### ads_offers_list The brand's new-advertiser offers per ad network, one row per ad account (or a network not connected yet): status, spend so far, what is left to spend, the daily pace and the deadline, and how to claim. Read-only. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/offers. ### ads_offer_update Records the claim of one offer row (`claimId` = a row id from ads_offers_list): status, the date it was claimed, and notes. Owners and admins of the brand only. A record only: it never creates, turns on or funds an ad. Kind: write. Scope: write. Endpoint: PATCH /api/v2/ads/offers/{claimId}. ### lead_booking_slots The next free times on the brand's connected Google or Microsoft calendar for a call with one lead, under the brand's booking rules (length, buffers, hours). Read-only. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/leads/{leadId}/booking-slots. ### lead_book_call Sends the lead a calendar invite with a Meet or Teams link at a free slot from lead_booking_slots, and marks the lead booked. Pass `attendeeEmail` only when the lead has no email on file. Moves no money. Kind: write. Scope: write. Endpoint: POST /api/v2/ads/leads/{leadId}/book. ### ads_site_tags_get flayr.social's ad tags per network (reddit, tiktok, linkedin, x, google, pinterest, snapchat): saved id, env default, requested, effectively on. Read-only. Site-wide: the connected account must be a flayr super-admin, or its brand must be in FLAYR_SITE_TAG_BRAND_IDS (else ADS_SITE_TAG_NOT_ALLOWED). Needs the ads:manage scope. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/site-tags. ### ads_site_tag_set Sets ONE network's tag on flayr.social (network, id, enabled, conversion references). Fields left out keep their saved value. A tag turns on only after the consent decision is recorded. Audited in Ads > Agent activity. Spends nothing. Pass agentName and reason. Site-wide: the connected account must be a flayr super-admin, or its brand must be in FLAYR_SITE_TAG_BRAND_IDS (else ADS_SITE_TAG_NOT_ALLOWED). Needs the ads:manage scope. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/site-tags. ### ads_tiktok_pixels_list The TikTok pixels on the brand's selected TikTok ad account: numeric id (for campaign optimization), pixel code (siteTagId, for the site), status, last fired. Read-only. Needs the ads:manage scope. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/site-tags/tiktok/pixel. ### ads_tiktok_pixel_ensure Reuses the TikTok pixel named "flayr.social" (or name / tagId) on the selected TikTok ad account, or creates it when none matches (audited), then saves its pixel code as the site's TikTok tag (save, default true; enable to turn it on). A failed create returns manualStep with the TikTok Ads Manager steps. Pass agentName and reason. Site-wide: the connected account must be a flayr super-admin, or its brand must be in FLAYR_SITE_TAG_BRAND_IDS (else ADS_SITE_TAG_NOT_ALLOWED). Needs the ads:manage scope. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/site-tags/tiktok/pixel. ### ads_page_get The Facebook Page the brand's Meta ads run as (pageId, name, status: active / needs_reconnect / not_connected) and the candidates: the brand's own connected Facebook accounts. Every Meta create runs as this Page when set. Read-only. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/page. ### ads_page_set Picks the Facebook Page the brand's Meta ads run as, from the brand's ALREADY connected Facebook accounts (ads_page_get lists them); pageId null clears it. Never connects an account (ADS_PAGE_NOT_CONNECTED lists the candidates). Owner/admin, audited in Ads > Agent activity. Spends nothing. Pass agentName and reason. Needs the ads:manage scope. Kind: write. Scope: ads:manage. Endpoint: PUT /api/v2/ads/page. ### brand_business_details_get A brand's legal name, registered address, website, currency and timezone: what ad networks ask for when you open an ads account. `hasTaxId` says whether a tax id is on file; the tax id itself is never returned. Use an `id` from list_brands. Kind: read. Scope: read. Endpoint: GET /api/v2/brands/{id}/business-details. ### brand_business_details_update Sets a brand's legal name, registered address, currency (ISO, like USD) and/or timezone (IANA, like America/New_York). Only the fields sent change; a brand with no details yet needs all four. Do not send a tax id: it is refused. A brand owner or admin adds it in flayr (Brand › Overview). Kind: write. Scope: write. Endpoint: PATCH /api/v2/brands/{id}/business-details. ### brand_mailbox_get Whether the brand sends lead follow-ups from its own mailbox: the address, provider, status, daily send cap (limit, remaining, reset), the fallback when it cannot send (resend = flayr's sender, hold = do not send) and open/link tracking. Use an `id` from list_brands. Kind: read. Scope: read. Endpoint: GET /api/v2/brands/{id}/mailbox. ### brand_mailbox_connect_link A one-time link that connects the business's own Gmail, Microsoft or IMAP mailbox to the brand. Give it to the person who owns the mailbox: they open it signed in to flayr and approve with their provider. Optional `email` pre-fills the address; `reconnect: true` refreshes an expired connection. Kind: write. Scope: write. Endpoint: POST /api/v2/brands/{id}/mailbox/connect-link. ### brand_mailbox_send_test Sends one test email from the brand's connected mailbox to your own account address. It never falls back to flayr's sender, so `sent: true` proves the mailbox works; otherwise `reason` says why (for example cap_reached or disconnected). Kind: write. Scope: write. Endpoint: POST /api/v2/brands/{id}/mailbox/test. ### brand_mailbox_contact_thread One contact's email with the brand: the threads in the brand's real mailbox, plus what flayr sent them from it with opens, clicks, bounces and the latest reply. Pass the contact as `email`; page with `cursor` and `limit` (1-100). Kind: read. Scope: read. Endpoint: GET /api/v2/brands/{id}/mailbox/threads. ### brand_sending_identity_get Who the brand's lead follow-up email comes from: mode flayr ("<Brand> via flayr"), domain (the brand's own domain, only once verified) or mailbox (its connected mailbox); the reply-to; the domain's DNS records, status, warm-up and bounce health; and a preview of each From line. Use an `id` from list_brands. Kind: read. Scope: read. Endpoint: GET /api/v2/brands/{id}/sending-identity. ### brand_sending_identity_set Choose `mode` (flayr, domain or mailbox), the display `fromName`, `replyTo`, `repliesTo` (brand or flayr) and `fromLocalPart` (before the @ on the brand domain). domain needs brand_sending_domain_add first; mailbox needs a connected mailbox. An empty string clears fromName or replyTo. Kind: write. Scope: write. Endpoint: PUT /api/v2/brands/{id}/sending-identity. ### brand_sending_domain_add Registers the brand's `domain` (e.g. example.com) for sending. Returns its status; the DNS records to publish are in brand_sending_identity_get. Nothing is sent from the domain until it is verified. Kind: write. Scope: write. Endpoint: POST /api/v2/brands/{id}/sending-identity/domain. ### brand_sending_domain_verify Asks the email provider to check the domain's DNS records now and returns the status (pending while DNS propagates, verified when ready). Kind: write. Scope: write. Endpoint: POST /api/v2/brands/{id}/sending-identity/domain/verify. ### brand_sending_domain_remove Removes the brand's sending domain. A brand in domain mode goes back to sending from flayr. Kind: destructive. Scope: write. Endpoint: DELETE /api/v2/brands/{id}/sending-identity/domain. ### brand_sending_identity_send_test Sends one test email to your own account address with the brand's current identity and reports the From actually used (`via` mailbox or resend; a domain that is not verified yet shows the flayr address). Kind: write. Scope: write. Endpoint: POST /api/v2/brands/{id}/sending-identity/test. ### ads_campaigns_import Import one resumable page of prior campaigns, ad sets, ads and available daily results from the selected connected ad account. No vendor writes or spend. Repeat while in_progress; blocked needs retry, busy means another request owns the page. Read status with ads_campaign_import_status. Does not provide Meta Marketing API or file backfill. Kind: write. Scope: write. Endpoint: POST /api/v2/ads/imports. ### ads_campaign_import_status Read the selected account import state, cursor, counts, result window and partial hierarchy warning in the active brand. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/imports. ### ads_snapshot_collect Save an immutable, org and brand scoped snapshot for selected ad accounts and an inclusive 1–30 day window. Reads vendors only; no charge, analysis, ad writes or spend. Each source reports availability. Kind: write. Scope: write. Endpoint: POST /api/v2/ads/snapshots. ### ads_snapshots_get Read one saved ads data snapshot by id, or recent snapshot headers for the active brand. No cross-org access. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/snapshots. ### ads_deep_dive_quote The Embers price of a deep dive on a saved snapshot, and whether a recent run makes it free. Charges nothing. Ask the owner before running. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/deep-dives/quote. ### ads_deep_dive_run Run a deep dive on a saved snapshot and save the report. Charges Embers only when confirmEmbers equals the current quote total; a failed run is refunded. Changes no ad, budget or campaign. Kind: write. Scope: write. Endpoint: POST /api/v2/ads/deep-dives. ### ads_deep_dive_get One saved deep dive by id, as json or an export (markdown, csv, pdf) of the stored report. List recent runs with GET /api/v2/ads/deep-dives. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/deep-dives/{id}. ### ads_deep_dive_compare Compare an older and a newer saved run: each finding is new, resolved, worse, better or unchanged, with metric deltas. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/deep-dives/compare. ### ads_checkpoints_get Scheduled check-ins for one campaign (default day 3, 7 and 14 after activation): whether they are on, the Embers price of each, and every past check-in with its spend, findings and charge. Charges nothing. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/campaigns/{id}/checkpoints. ### ads_checkpoints_set Switch scheduled check-ins on or off for one campaign (owner or admin only). Switching on makes each future check-in charge Embers, so it needs confirmEmbers equal to checkpointEmbers from the read tool; ask the owner first. A check-in under the minimum spend is skipped free. Changes no ad, budget or campaign. Kind: write. Scope: write. Endpoint: POST /api/v2/ads/campaigns/{id}/checkpoints. ### ads_learned_insights The insights library: finished experiments and deep-dive verdicts confirmed across runs (worked / did not work), each deep-dive one with its evidence and report link. Pass `platform` to also get the do/avoid suggestions for a new campaign there; `source` filters to experiment or deep_dive. Read only. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/learned-insights. ### ads_boost_candidates The brand's published posts ranked for a boost (reach, engagement rate, link clicks, recency and timeliness), with window/windowLabel (Boost now or Upcoming), separate missedWindows for expired posts that cannot be boosted, upcomingDates from the shared season config, score parts, the call-to-action link found, and whether an ad account is connected for the network. Removed posts, posts with no call to action and networks a boost can't run on are left out. Read-only: nothing is boosted or charged. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/boost-candidates. ### ads_auto_judge The brand's scheduled auto-judge: its settings (off by default) and recent proposal groups, one per run. Each post gets one call (boost, ad or let go) with budget, window, season end, reason, the stored prediction and whether it is over the owner's caps or the agent limits. A missed-window post is only ever let go. Read-only: approving, rejecting and changing the settings stay with the owner or an admin in the app; nothing is activated or charged. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/auto-judge. ### ads_lead_replies_get The brand's lead response rule for click-to-message ads: whether a person who types to the ad gets an automatic first reply in the same Messenger/Instagram DM thread (off by default), its text ({{name}} = first name; null = the greeting), the platform window in hours, and up to 20 recent leads with when they were answered. No message text. Read-only. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/lead-replies. ### ads_lead_replies_set Switches the automatic first DM reply for messaging-ad leads on or off (firstReplyEnabled) and sets its text (firstReplyText, up to 600 characters; null uses the greeting; omit to keep it). Needs ads:manage and an owner or admin of the brand. Each new conversation gets it once, only inside the platform window. Free: nothing is charged. Confirm the text with the user first: it is sent to real people. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/lead-replies. ### ads_launch_review Every paused campaign of the brand on every network, with each ad's text, headline, button and destination, and the pre-launch checks (destination resolves, UTM tags, button, end date or lifetime budget, max spend, call to action, same destination across networks), each pass, warn or fail. Read-only: it never switches a campaign on or spends; switching on stays with the owner in the app. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/launch-review. ### ads_page_layout The /ads page's tabs (Insights, Campaigns, Ads, Leads, Setup, Pending, Custom), each tab's sections, who sees each (boost = Pro and up, manage = Premium and up, advanced = Advanced nav mode only), and the API v2 path and MCP tool that return each section's data. Deep-link a tab with /ads?tab=<value>. Read-only. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/layout. ### get_ads_command_center_config flayr admins only: the businesses the Ads command center reports on (funnel steps, primary conversion, pinned ad accounts, sources, enabled), the alert rules and the rollup window. Steps with no source yet are "not connected", never 0. Read-only. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/command-center/config. ### get_ads_history_backfills flayr admins only: per selected Meta ad account, the history import that brings in campaigns that ran before the account was connected: status, date range, progress and row counters. A missing Meta permission names the exact scope (missingScope). Read-only: it never starts an import, spends or edits a campaign. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/history-backfills. ### ads_accounts_list The brand's ad account with its currency, spend limit, balance (minor units) and readiness. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/accounts. ### ads_campaigns_list The brand's ad campaigns with status, budget, start/end dates, max spend, spend to date, ad sets and ads. Filter by status or platform. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/campaigns. ### ads_campaign_get One ad campaign by its Flayr id, with its ad sets and ads, including each ad's network review status, reason when available, and last sync time. Do not invent a rejection reason when the network supplies none. On a Meta campaign each ad also carries page { pageId, name, handle }: the Facebook Page it runs as (null when not reported); ads_page_get shows the brand's picked ads Page. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/campaigns/{id}. ### ads_insights Impressions, clicks, spend, link clicks and leads per campaign for a date range (default the last 30 days, at most 93), with totals per currency. Pass `level: "ad"` for daily per-ad results summed per ad (spend, impressions, clicks, CTR, video views), each with the Library `contentId` the ad was built from (null when unlinked; `unlinked` counts those). Kind: read. Scope: read. Endpoint: GET /api/v2/ads/insights. ### ads_readiness Whether each connected network and ad account can run ads, and what to fix first. Pass `objective` (the campaign objective, e.g. `lead_generation` for an Instant Form campaign) before activating: each check then says whether it `blocks` that objective or is `advisory`, and `overall` counts only the blocking ones. A blocking check in state `manual` is not readable by API: confirm it on the platform. networkSwitches lists, per network, whether ad creation and boosts are switched on, the daily minimum (minor units), and whether ads_campaign_create can create there (keyCreate). Every network, connected or not, also lists `setup` (connect, ad account, payment method, conversion tracking, claim the new-advertiser offer; each done, missing or check, with the platform page) and `offer` (the offer terms, null when none). Claim an offer before the first campaign spends; mark it claimed and track its spend with ads_offers_list and ads_offer_update. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/readiness. ### ads_campaign_pause Pauses a live ad campaign on its ad network so it stops spending (`action: "pause"` or `"stop"`; both leave it paused). Pausing never needs the owner's approval and is never limited by the agent ceiling. To approve and switch on a proposed campaign use ads_campaign_approve. Confirm with the user first. Kind: write. Scope: write. Endpoint: POST /api/v2/ads/campaigns/{id}/pause. ### ads_delete_campaign DESTRUCTIVE: permanently deletes an ad campaign in flayr and on its ad network. Cannot be undone; to stop spending but keep the campaign use ads_campaign_pause. A running campaign, or one that spent today, is refused unless `stopFirst: true`, which pauses it first. The answer reports whether it is gone in flayr (`flayr`) and on the network (`network`). Pass an `idempotencyKey` so a retry never deletes twice. Confirm with the user first. Kind: destructive. Scope: ads:manage. Endpoint: DELETE /api/v2/ads/campaigns/{id}. ### ads_import_preview What an Ads Manager export (CSV text, or a base64 .xlsx) would import, without writing: the column mapping found, columns left unmapped, the first rows, malformed rows by line number, and each conflict with a synced row (the synced value is kept). Run this before ads_import_commit. Kind: read. Scope: read. Endpoint: POST /api/v2/ads/imports/files/preview. ### ads_import_commit Import the rows of an Ads Manager export as imported reporting rows, in one batch that ads_import_undo takes back. A synced row is never overwritten; only metrics it does not report are filled. The same file twice changes nothing. Spends nothing, calls no ad network, changes no budget. Confirm with the user first. Kind: write. Scope: write. Endpoint: POST /api/v2/ads/imports/files. ### ads_import_list The workspace's stats file imports, newest first: file, network, date range, row counts, and whether each was undone. No cross-org access. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/imports/files. ### ads_import_get One import by id: the campaigns, ad sets and ads it brought in with their totals. A metric the file did not report is null, never 0. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/imports/files/{id}. ### ads_import_undo Take one import back: rows it created are removed and metrics it filled on synced rows are cleared. Synced data is never touched. Confirm with the user first. Kind: write. Scope: write. Endpoint: POST /api/v2/ads/imports/files/{id}/undo. ### ads_caps_get The brand's activation spend caps and what is committed against them this month, the owner's agent ceilings, and the ad account spending limit with what is left of it (all in cents). Pass campaignId to learn what ads_campaign_approve with activate: true would answer right now: `applied` (it switches on), `approval_requested` (the owner gets an approval request) or `refused` with the reason. Read it before activating, and tell the user which one to expect. It covers flayr's own checks; the ad network can still refuse. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/caps. ### ads_caps_set Sets the brand's monthly and/or per-campaign activation caps, in cents (e.g. 50000 = $500). Needs the ads:budget scope; a cap above the owner's agent ceiling is an approval request, never applied. Guardrails: flayr enforces the owner's agent ceiling (per month, per campaign, per day) on the server; you cannot raise it. Inside it the change is applied at once; above it nothing changes and the result is `approval_requested` (HTTP 202) with `approvalId` and `approvalUrl`, the owner's one-click approval link: give it to the user (an owner can also decide approvalId with approvals_decide, through a different connection). When the owner set approvals to API/MCP/chat only (`assistantOnly: true`) there is no link: tell the user to approve approvalId with approvals_decide or in flayr chat. Either way, repeat the exact same call once the owner approves (the approval covers that call once). Every call is audited (Ads > Agent activity) and the owner gets a daily digest. Pass agentName and reason; both are shown to the owner. Kind: write. Scope: ads:budget. Endpoint: POST /api/v2/ads/caps. ### ads_account_spend_limit_set Sets the Meta ad account spending limit, in the account currency (e.g. 800 = $800). Removing the limit (null) always needs the owner. Guardrails: flayr enforces the owner's agent ceiling (per month, per campaign, per day) on the server; you cannot raise it. Inside it the change is applied at once; above it nothing changes and the result is `approval_requested` (HTTP 202) with `approvalId` and `approvalUrl`, the owner's one-click approval link: give it to the user (an owner can also decide approvalId with approvals_decide, through a different connection). When the owner set approvals to API/MCP/chat only (`assistantOnly: true`) there is no link: tell the user to approve approvalId with approvals_decide or in flayr chat. Either way, repeat the exact same call once the owner approves (the approval covers that call once). Every call is audited (Ads > Agent activity) and the owner gets a daily digest. Pass agentName and reason; both are shown to the owner. Kind: write. Scope: ads:budget. Endpoint: POST /api/v2/ads/accounts/spend-limit. ### ads_ad_set_placements Changes where an existing ad set runs. `excludeAudienceNetwork: true` keeps Facebook, Instagram and Messenger and drops Audience Network; or pass an explicit publisherPlatforms list. `id` is the ad set id from ads_campaign_get. Pass agentName and reason. Audited in Ads > Agent activity. It cannot be undone from there: to change it back, call this tool again with the earlier settings. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/ad-sets/{id}/placements. ### ads_ad_set_dataset Attaches a Meta dataset (pixel) to an existing ad set, optionally with the conversion event (e.g. PURCHASE). Pass agentName and reason. Audited in Ads > Agent activity. It cannot be undone from there: to change it back, call this tool again with the earlier settings. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/ad-sets/{id}/dataset. ### ads_campaign_approve Approves a proposed ad campaign (ads:manage or ads:activate). With activate: true it also switches it on (needs ads:activate), through the normal activation checks, when its daily budget is within the owner's per-day agent ceiling. Read ads_caps_get with campaignId first to know the answer. Guardrails: flayr enforces the owner's agent ceiling (per month, per campaign, per day) on the server; you cannot raise it. Inside it the change is applied at once; above it nothing changes and the result is `approval_requested` (HTTP 202) with `approvalId` and `approvalUrl`, the owner's one-click approval link: give it to the user (an owner can also decide approvalId with approvals_decide, through a different connection). When the owner set approvals to API/MCP/chat only (`assistantOnly: true`) there is no link: tell the user to approve approvalId with approvals_decide or in flayr chat. Either way, repeat the exact same call once the owner approves (the approval covers that call once). Every call is audited (Ads > Agent activity) and the owner gets a daily digest. Pass agentName and reason; both are shown to the owner. Confirm with the user before activating. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/campaigns/{id}/approve. ### ads_campaign_scale Changes a campaign's campaign-level budget to budgetMinor (whole cents, e.g. 4000 = $40), keeping its type: a daily budget is held to the owner's per-day agent ceiling, a lifetime budget to the per-campaign ceiling (read both with ads_caps_get). Scaling down is always inside the ceiling. Uses the same budget rules and activation spend caps as the dashboard; pass idempotencyKey to make a retry safe. Guardrails: flayr enforces the owner's agent ceiling (per month, per campaign, per day) on the server; you cannot raise it. Inside it the change is applied at once; above it nothing changes and the result is `approval_requested` (HTTP 202) with `approvalId` and `approvalUrl`, the owner's one-click approval link: give it to the user (an owner can also decide approvalId with approvals_decide, through a different connection). When the owner set approvals to API/MCP/chat only (`assistantOnly: true`) there is no link: tell the user to approve approvalId with approvals_decide or in flayr chat. Either way, repeat the exact same call once the owner approves (the approval covers that call once). Every call is audited (Ads > Agent activity) and the owner gets a daily digest. Pass agentName and reason; both are shown to the owner. Confirm the new amount with the user first. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/campaigns/{id}/budget. ### ads_lead_forms_list The Meta Instant Forms (lead forms) on the brand's selected ad account: id, name, status. Use a form id as leadGenFormId in ads_campaign_create. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/lead-forms. ### ads_lead_form_create Creates a Meta Instant Form on the brand's selected ad account: name, privacyPolicyUrl (https), questions (Meta question objects, e.g. { type: "EMAIL" }, { type: "FULL_NAME" }, or a CUSTOM question with label and options), optional contextCard, thankYou* fields and followUpActionUrl (same fields as the dashboard form). Same builder and limits as the dashboard. One vendor call, never retried; pass idempotencyKey to make repeats safe. Pass agentName and reason. Audited in Ads > Agent activity. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/lead-forms. ### ads_lead_form_consent_get The brand's saved lead consent (text, version, title, checkboxLabel), whether leads are stored (enabled) and emailed (followUpEnabled), the code defaults, and the forms already created with the consent checkbox. Needs ads:manage. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/lead-forms/consent. ### ads_lead_form_consent_set Saves the brand's lead consent: consentText, consentVersion (a new version is required when the wording changes), consentTitle, consentCheckboxLabel, and the switches enabled (store leads) and followUpEnabled (email leads who ticked consent; needs enabled). Every field left out keeps its saved value, then the default (v1 wording). Required before ads_lead_form_consent_copy. Pass agentName and reason. Confirm with the user before turning followUpEnabled on: it emails real leads. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/lead-forms/consent. ### ads_lead_form_consent_copy Copies a live Meta Instant Form (copyFromFormId) into a new form with the same questions, pages and privacy link, plus the brand's saved consent checkbox (save it first with ads_lead_form_consent_set). Optional name. Meta forms cannot be edited, so this is how an ad gets consent; then point the ad at the new formId with ads_lead_form_swap_ad. One vendor call, never retried. Pass agentName and reason. Audited in Ads > Agent activity. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/lead-forms/consent-copy. ### ads_lead_form_swap_ad Points a live Meta lead ad (adId) at another Instant Form (newFormId) without Ads Manager: creates a new ad PAUSED in the same ad set with the same copy and media and the new form, switches it on, and only then pauses the old ad. Returns oldAdId and newAdId. A failed step stops there and says what serves. Single-image and single-video ads only. Pass idempotencyKey to make a retry safe, and agentName and reason. Audited in Ads > Agent activity. Confirm with the user first. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/lead-forms/swap-ad. ### ads_audiences_list The brand's Meta custom and lookalike audiences (id, name, type, preset, size) and the owner's audience limits (presets on, most included / excluded per ad set, lookalike ratio range, customer-list batch size). Put the ids in includeAudienceIds / excludeAudienceIds of ads_campaign_create, or use one as seedAudienceId of a lookalike. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/audiences. ### ads_audience_create Creates a Meta custom audience on the brand's selected ad account from a preset: site_visitors (the brand's Meta pixel visitors), signup_page_visitors (pixel visits to the sign-up page; urlContains overrides the configured path), trial_starters (people who fired the trial event), customer_list (empty; fill it with ads_audience_users_add) or lookalike (seedAudienceId from ads_audiences_list, country, ratio). retentionDays sets the website window. Website presets need the brand's Meta pixel (409 ADS_NO_META_PIXEL). Which presets are on and the ranges are the owner's ads config (403 AUDIENCE_PRESET_DISABLED). An audience never spends. Pass agentName and reason. Audited in Ads > Agent activity. Guardrails: flayr enforces the owner's agent ceiling (per month, per campaign, per day) on the server; you cannot raise it. Inside it the change is applied at once; above it nothing changes and the result is `approval_requested` (HTTP 202) with `approvalId` and `approvalUrl`, the owner's one-click approval link: give it to the user (an owner can also decide approvalId with approvals_decide, through a different connection). When the owner set approvals to API/MCP/chat only (`assistantOnly: true`) there is no link: tell the user to approve approvalId with approvals_decide or in flayr chat. Either way, repeat the exact same call once the owner approves (the approval covers that call once). Every call is audited (Ads > Agent activity) and the owner gets a daily digest. Pass agentName and reason; both are shown to the owner. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/audiences. ### ads_audience_users_add Adds people to a customer_list audience (audienceId from ads_audiences_list or ads_audience_create): users is a list of { email?, phone? }, phones with the country code. Values are normalised and deduplicated; already-hashed SHA-256 values pass through; rows without a valid email or phone are skipped and counted. At most the configured batch size per call. flayr never stores the people sent; the audit keeps counts and a digest. Only upload people the brand has consent to advertise to. Pass agentName and reason. Audited in Ads > Agent activity. Guardrails: flayr enforces the owner's agent ceiling (per month, per campaign, per day) on the server; you cannot raise it. Inside it the change is applied at once; above it nothing changes and the result is `approval_requested` (HTTP 202) with `approvalId` and `approvalUrl`, the owner's one-click approval link: give it to the user (an owner can also decide approvalId with approvals_decide, through a different connection). When the owner set approvals to API/MCP/chat only (`assistantOnly: true`) there is no link: tell the user to approve approvalId with approvals_decide or in flayr chat. Either way, repeat the exact same call once the owner approves (the approval covers that call once). Every call is audited (Ads > Agent activity) and the owner gets a daily digest. Pass agentName and reason; both are shown to the owner. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/audiences/{audienceId}/users. ### ads_targeting_search Searches the brand's selected ad account for targeting ids by name: q (2+ characters), dimension (default interest; also behavior, demographic, geo with geoType and countryCode), limit. Returns { results: [{ id, name, path?, audienceSize? }] }; put the ids in targeting.interests of ads_campaign_create. Read-only. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/targeting/search. ### ads_campaign_create Creates a Meta Instant Form lead campaign (goal lead_generation, the ad set's leadGenFormId from ads_lead_forms_list, placements without Audience Network, the age range and countries in targeting) with one image ad, or video ads, created PAUSED. It lands in the owner's Proposed campaigns and never runs or spends until the owner approves it (ads_campaign_approve). headline, body, one creative and budget (dollars; budgetType daily or lifetime) are required. The creative is one of: imageUrl (https on an allowed host: *.convex.cloud, img.clerk.com, ui-avatars.com, images.unsplash.com, *.googleusercontent.com, cdn.shopify.com, commerce.mdostal.com, shop.mdostal.com; anything else, upload it with POST /api/v2/media/upload-url), imageMediaId (that upload's storageId), creativeId, video, or videos (several video ads in one ad set for an A/B test, each { mediaId | contentId | metaVideoId, name?, thumbnailUrl? }). placements: automatic (default), facebook, instagram, facebook_instagram, feeds, reels, stories, or { platforms, surfaces }; never Audience Network. savedTargetingId reuses a saved audience (Ads > Audiences) under your own targeting; includeAudienceIds and excludeAudienceIds (Meta lead and website campaigns, FFE-1602) attach custom / lookalike audiences from ads_audiences_list to the ad set, or exclude them (for example existing customers), up to the owner's per-ad-set limits (400 AUDIENCE_LIMIT); raw Meta audience ids in targeting are refused; interest ids come from ads_targeting_search. promotedObject.pageId picks the Facebook Page. goal messages instead creates a click-to-message ad (Messenger + Instagram Direct, imageUrl only, no form): the brand's automatic first reply greets people with quick replies tagged with armKey, and each conversation lands as a lead with its ad/arm attribution; also PAUSED and proposed. goal traffic or conversions (FFE-1537) creates a website campaign that sends people to targetUrl (required; UTM parameters are added from the owner's ads config): the same creative sources, or creatives (several image ads in one ad set, each { imageUrl | imageMediaId | creativeId, headline?, body?, description?, linkUrl?, name? }), plus description (the line under the headline) and callToAction. conversions optimizes for a pixel event on the brand's selected pixel (promotedObject.customEventType, default COMPLETE_REGISTRATION) and is refused with code PIXEL_NOT_PROVEN unless the readiness check `pixel` passes: read ads_readiness with objective conversions first and tell the user what it says to fix. Per ad set (FFE-1600, Meta website campaigns): optimizationGoal picks what the ad set optimises for: link_clicks or landing_page_views (goal traffic), complete_registration, start_trial or paid_conversion (goal conversions on the brand's pixel, the same PIXEL_NOT_PROVEN check; paid_conversion uses the owner's paid event, Purchase or Subscribe); goal may then be left out, and promotedObject.customEventType is not sent with it. bidStrategy is highest_volume (Meta gets the most results for the budget, the default), cost_per_result (an average cost-per-result goal) or bid_cap (a hard cap per auction); costPerResultGoal is that amount in dollars (for example 20 for $20 per sign-up) and on its own means cost_per_result. Which goals and strategies are on and the cost-per-result range are the owner's ads config: a refusal answers 400 with code OPTIMISATION_GOAL_NOT_ALLOWED, BID_STRATEGY_NOT_ALLOWED or COST_PER_RESULT_OUT_OF_RANGE and says what is allowed. platform tiktok with goal traffic or conversions creates a TikTok video campaign on the brand's connected TikTok ad account instead (video or videos as { libraryItemId | storageId }, a daily budget, schedule.endDate, targeting.countries, an https targetUrl, and promotedObject.pixelId for conversions); it answers 403 until the owner's admin has enabled TikTok ad creation. platform twitter (or x, FFE-1606) creates an X website-card campaign on the brand's connected X ad account: goal traffic, engagement or awareness (required), headline (card title, up to 70 characters), body (post text, up to 256), imageUrl (https card image), targetUrl (https), a daily budget at or above the X daily minimum, schedule.endDate, and targeting.countries only; description, callToAction, video and creatives are refused. It answers 403 NETWORK_CREATE_DISABLED until the owner has switched X creation on (Ads > Spend controls > Networks). platform google, linkedin, reddit or pinterest (FFE-1606) creates the same campaign the dashboard builds for that network on its connected ad account, with the same validation (google: the google object (campaignType, headlines, descriptions, images...) plus headline, body, targetUrl and a daily budget; linkedin: headline, body, imageUrl or video, targetUrl, daily budget; reddit: headline, one of imageUrl, video or carouselCards, targetUrl, daily or lifetime budget; pinterest: headline, imageUrl, targetUrl, optional boardId, daily or lifetime budget), each answering 403 NETWORK_CREATE_DISABLED until the owner has switched that network's creation on. To boost an already-published X post instead, use ads_boost_create. ads_readiness lists networkSwitches: per network, whether create and boost are on, the daily minimum, and whether this tool can create there (keyCreate). Every campaign from this tool is PAUSED and proposed; a budget above the owner's caps is refused. Pass agentName and reason. Audited in Ads > Agent activity. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/campaigns. ### ads_boost_create Boosts a post the brand has already published on X, as published, through the brand's selected X Ads account. platform twitter (or x), postId (a flayr post id; ads_boost_candidates ranks them) or contentId, a whole-dollar daily budget at or above the X daily minimum, countries (2-letter codes), an end (endDate or durationDays), optional goal (engagement, traffic, awareness, video_views) and startDate. Created PAUSED in the owner's Proposed campaigns: nothing runs or spends until the owner approves it (ads_campaign_approve with activate). The exposure (daily x days) must fit the owner's caps. Answers 403 NETWORK_BOOST_DISABLED until the owner has switched X boosts on (ads_readiness networkSwitches shows it), 409 ADS_ACCOUNT_REQUIRED without a selected X Ads account; other platforms answer 400 PLATFORM_NOT_SUPPORTED. Pass agentName and reason. Audited in Ads > Agent activity. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/boosts. ### ads_conversion_test_event Sends ONE server-side CompleteRegistration to a Meta pixel on the brand's selected ad account with Meta's test code (testEventCode, from Events Manager → the dataset → Test events; required), to prove the Conversions API path delivers. Optional pixelId (default: the pixel saved for the ad account, or its only active one). It creates nothing and spends nothing, and never sends without a test code. outcome "delivered" only when Meta counted the event; "rejected" carries Meta's error codes in failureCodes. 409 ADS_PIXEL_NOT_ON_AD_ACCOUNT lists the pixels Meta has for the ad account and the step to share the missing one. The event cannot be taken back: Meta also counts it in the dataset totals. Needs agentName and reason, and the ads:manage scope. Kind: write. Scope: ads:manage. Endpoint: POST /api/v2/ads/conversions/test-events. ### ads_agent_activity Recent agent actions on ads (agent name, reason, outcome), owner approval requests still pending, and the owner's agent ceilings. Use it to see whether an approval request was decided. Kind: read. Scope: read. Endpoint: GET /api/v2/ads/agent/activity. ### get_campaign_review A campaign's pieces grouped into review sections (episode, week, channel set, variant group or the creator's own). Each piece has preview URLs (video / images / audio), caption, labels, its bookings (channels, time, review state) and QA checks; each section has its status, round and every previous fix note. Share `reviewUrl` so a person can preview and decide in flayr. Kind: read. Scope: read. Endpoint: GET /api/v2/campaigns/{id}/review. ### group_campaign_review Puts the campaign's not-yet-sectioned pieces into review sections (groupBy: week, channel_set, variant_group, episode or phase; default the brand's setting). Existing sections and decisions are kept. Kind: write. Scope: publish. Endpoint: POST /api/v2/campaigns/{id}/review. ### decide_campaign_review_section action "approve" approves the section's pending pieces (or pieceIds) and their held posts GO LIVE at their slots — needs the explicit `review` scope (admin does not include it); QA-failed pieces are skipped unless overrideQa. "fix" sends the pieces back with a `note` (required): their posts are taken off the schedule and the section opens a new round; other sections are untouched. "drop" takes the posts off the schedule and drops the pieces. "ready" puts fixed pieces back up for review. fix/drop/ready need `review` or `publish`. Agency plan. Confirm with the user first. Kind: publish. Scope: read. Endpoint: POST /api/v2/campaigns/{id}/review/sections/{sectionId}. ### list_campaign_analytics Running, planned and recently finished campaigns (organic, paid or mixed), each with dates, status, posts published of planned, reach, impressions, engagements, link clicks, and for paid spend and cost per result, the goal with its success measure (`success`), plus a daily impressions trend and `overlay` (success measure and reach to date by day of campaign, to overlay campaigns by date or by campaign day). `aggregate` is all listed campaigns together, with a daily series. Posts in no campaign roll up under `notInCampaign`. A null measure means not reported by any network, never zero. Kind: read. Scope: read. Endpoint: GET /api/v2/campaigns/analytics. ### get_campaign_analytics One campaign's full picture: reach and engagement over time, per network, best and worst posts, and for paid the split by ad (with reach) and best/worst ads. `seriesBasis` says whether organic days are stored daily growth or publish-day estimates. `previousCampaign` names the campaign before it, with a compare link and its `overlay`; `trend` compares success and reach against it at the same day of campaign. A null measure means not reported. Kind: read. Scope: read. Endpoint: GET /api/v2/campaigns/{id}/analytics. ### compare_campaigns Two or more campaigns side by side (`ids` comma-separated, e.g. organic vs organic, organic vs paid, or a campaign against its previous one): the same totals, per-network split, best/worst posts, and cumulative series by day since each start so they overlay. Unknown ids come back in `missing`. Kind: read. Scope: read. Endpoint: GET /api/v2/campaigns/compare. ### get_post_analytics Every metric the networks report for one published post: reach, impressions, plays, average watch time, watch-through, likes, comments, shares, saves, profile visits, follows and link clicks, per network and in total. Video posts carry the retention curve with the hook window, average view duration and the point where half the viewers had left (`retention`); other posts carry a funnel from reach to engaged to clicked to converted (`funnel`). `settling` means the network may still change the numbers; `history` holds the 48h, 7d and 30d snapshots. Boosted posts add spend and cost per result (`paid`). A null measure means not reported by that network, never zero. Kind: read. Scope: read. Endpoint: GET /api/v2/posts/{id}/analytics. ### get_video_explorer Every video and reel the brand published in a timeframe (`days`, snapped to 7, 30, 90 or 365 by default), one point per network: length, watch-through, reach, average watch time, engagement rate, hook retention and end retention. Short-form and long-form sections compare this period with the previous one of the same length. The hook board groups videos by `hook:` and Hook Studio `hook-template:` labels and names the hook that holds viewers through the first seconds (`bestAtHook`) and to the end (`bestToEnd`). Pass point ids to compare_videos to overlay retention curves. A null measure means not reported by that network, never zero. Kind: read. Scope: read. Endpoint: GET /api/v2/analytics/videos. ### compare_videos Retention curves of two or more videos, from point ids returned by get_video_explorer (`postId:platform`, comma-separated in `ids`). Each curve comes as share of the video and as seconds, so videos of different lengths overlay; `axis` says which unit fits them all. Videos the network has no curve for are listed in `missing` (not reported, never zero). Kind: read. Scope: read. Endpoint: GET /api/v2/analytics/videos/compare. ### get_post_siblings For one post: the same video posted again on other networks or days, and other variants of the same piece (`variant-of:`, `experiment:`, `ab:` and `hook-template:` labels), each with its per-network video numbers. A null measure means not reported, never zero. Kind: read. Scope: read. Endpoint: GET /api/v2/posts/{id}/siblings. ### estimate_campaign Plans a campaign arc from a brief (goal, dates, offer, products or source "brand" with the optional interview, platforms): every post slot with its phase and time, and the most Embers generating its drafts can cost. Creates nothing and charges nothing — use it to show the user the plan and the price before creating. The default goal is "engagement" (no offer, price or deadline needed); for the user's own goal pass goal "custom" with customGoal (their sentence, optional successMeasures and template). With no store, pass source "brand": the posts come from the brand, its Library and the optional interview. Kind: read. Scope: read. Endpoint: POST /api/v2/campaigns/builder/estimate. ### create_campaign_brief Creates a draft organic-social campaign and its brief in the brand — from its products, or with source "brand" from the brand, its Library and the optional interview (no store needed) — and returns the planned slots and the generation estimate. Takes the same brief as estimate_campaign (goal defaults to "engagement"; goal "custom" takes customGoal). Charges nothing and posts nothing. Kind: write. Scope: write. Endpoint: POST /api/v2/campaigns/builder. ### generate_campaign_drafts Starts writing a draft post for every slot of a builder campaign that has none yet. CHARGES EMBERS, up to the returned `estimate.embers`; a balance too low is refused up front (402 insufficient_credits) and nothing is charged. Confirm the cost with the user before calling. Runs in the background; calling again only fills slots still without a draft. Kind: write. Scope: write. Endpoint: POST /api/v2/campaigns/builder/{id}/generate. ### book_campaign Books every generated draft of a builder campaign into the campaign's own posting queue, each pinned to its slot time — the posts GO LIVE on the platforms at those times unless the brief requires review. Booking again skips drafts already booked; drafts too close to their time are returned in `skippedTooSoon`. Needs `publish`; Agency plan. Confirm with the user first. Kind: publish. Scope: publish. Endpoint: POST /api/v2/campaigns/builder/{id}/book. ### create_campaign_share Makes a PUBLIC review link for a campaign: a page, open to anyone who holds the link with no login, that shows the brand's drafts carrying `campaignLabel` (e.g. `campaign:<campaign id>`) and lets the reviewer approve or ask for changes. `expiresInDays` is one of `expiryDays` from list_campaign_shares. Give `site` and `requester` together to add the line "Made by flayr from the public pages of <site> for <requester>", or leave both out. The answer has `url` and `token` ONCE (flayr stores only a hash): give the user the `url` right away. `brandId` from list_brands (a brand-bound connection may omit it). Kind: write. Scope: write. Endpoint: POST /api/v2/campaign-shares. ### list_campaign_shares The review links of a brand, newest first: id, title, label, whether each is still active, when it expires and when it was last opened; plus `expiryDays`, the choices create_campaign_share accepts. Never a token or URL: those are shown once, when a link is made. Needs a connection with the write scope. `brandId` from list_brands (a brand-bound connection may omit it). Kind: read. Scope: read. Endpoint: GET /api/v2/campaign-shares. ### get_campaign_share_verdicts What the reviewer said through a review link, draft by draft: `decision` (approve, changes or deny), their comment and name. `contentId` is the draft (get_content). Needs a connection with the write scope. `id` from list_campaign_shares. Kind: read. Scope: read. Endpoint: GET /api/v2/campaign-shares/{id}. ### revoke_campaign_share DESTRUCTIVE: the public review link stops working at once and cannot be turned back on (make a new link instead). Verdicts already given stay readable. Confirm with the user first. `id` from list_campaign_shares. Kind: destructive. Scope: write. Endpoint: DELETE /api/v2/campaign-shares/{id}. ### pronunciations_list How every flayr voice (chat voice, voiceovers, character VO) says a brand's words: `pronunciations` (term → sayAs respelling, with `verified` when a Verify passed), `suggested` (learned suggestions, inert until accepted) and `builtIn` entries. Captions and transcripts keep the written word. `brandId` from list_brands, or `personal`. Kind: read. Scope: read. Endpoint: GET /api/v2/pronunciations. ### pronunciations_upsert Sets how voices say `term` for a brand: `sayAs` is a plain respelling (e.g. "Dahss-tuhl"). Updates the entry with that term (case-insensitive; accepts a waiting suggestion) or creates one; fields left out keep their values. `acceptedHearings` are transcriptions Verify also counts as a pass. Applies to every voice from the next render, with no per-call setup. Kind: write. Scope: write. Endpoint: POST /api/v2/pronunciations/upsert. ### pronunciations_verify Speaks a carrier sentence with the entry in a voice (default Gemini Puck), transcribes it, and passes when the transcript has the term or an accepted hearing. CHARGES EMBERS per check: only call it when the user asks, after telling them the price (GET /api/v2/pronunciations/{id}/verify quotes it; nothing is charged for a quote). Never refunded, even when the check fails or cannot run. `id` from pronunciations_list. Kind: write. Scope: write. Endpoint: POST /api/v2/pronunciations/{id}/verify. ### pronunciations_improve Runs one improve round: 3+ deliberately different samples of the entry, each with its respelling, script, transcript, word diff and accent check (`accent`, default en-US). Ask the user which sample is right and what was wrong with the others (wrong words, a note, a "say it like this" respelling), then either choose one with pronunciations_improve_choose or run another round with the same `sessionId` and ALL the `feedback` ({ round, sample, played, words, note?, sayItLike? }). CHARGES EMBERS: one charge covers up to 3 rounds (GET /api/v2/pronunciations/{id}/improve quotes it); the round after starts a new charge, and `billing.note` says so: tell the user before running it. Refunded when no sample could be made. Audio is left out unless `includeAudio` is true. Kind: write. Scope: write. Endpoint: POST /api/v2/pronunciations/{id}/improve. ### pronunciations_improve_choose Saves the chosen sample's respelling on the entry (verified when that sample passed its transcript check) and ends the improve session. `sessionId`, `round` and `sample` from pronunciations_improve. Free. Kind: write. Scope: write. Endpoint: POST /api/v2/voice/improve/sessions/{sessionId}/choose. ### pronunciations_improve_give_up Ends an improve session without changing the entry. Send any last `feedback`. Free. Kind: write. Scope: write. Endpoint: POST /api/v2/voice/improve/sessions/{sessionId}/abandon. ### list_voices Your ready voice clones in the brand (never a teammate's) and `defaultVoiceId`, the one generate_voice uses when `voiceId` is omitted. Free. `brandId` from list_brands, or `personal`; a brand-bound connection reads its own brand. Kind: read. Scope: read. Endpoint: GET /api/v2/generate/voice. ### generate_voice Speaks `text` (max 5,000 characters) in one of your voice clones and returns `audioUrl`. CHARGES EMBERS per 1,000 characters (cloned voices cost more than stock), checked first and charged to the brand's pool; a failed job is refunded. Tell the user the cost before calling. `voiceId` from list_voices (default: your newest clone in the brand). Kind: write. Scope: write. Endpoint: POST /api/v2/generate/voice. ### get_brand_voice The brand's default writing voice: tone, style and keywords to write copy in. Not a speaking voice (see list_voices). `brandId` from list_brands, or `personal`. Kind: read. Scope: read. Endpoint: GET /api/v2/brand/voices. ### music_tracks_list List the brand’s uploaded music with audio URLs, source, license, attribution, duration, mood/tags and ad-use guidance. A bound key only accesses its brand; brandId can select a brand for an account-wide key. includeArchived also returns archived tracks. Kind: read. Scope: read. Endpoint: GET /api/v2/music/tracks. ### music_tracks_create Add 1–50 uploaded audio tracks to a brand library atomically. First use upload_media for each file, POST its raw bytes to uploadUrl with Content-Type audio/mpeg (or the actual audio type), then pass the returned storageId and track metadata here. Include source, licenseCode and attribution; madeOn records the generation date for Suno music. No music generation or Ember charge. All tracks save or none do. Use stable externalIds from the manifest; list and compare them before retrying an uncertain result. Duplicates reject the whole batch. Kind: write. Scope: write. Endpoint: POST /api/v2/music/tracks. ### music_library_list List the live tracks in flayr’s own sound library with title, composer, mood, uses, energy, length, a thumbnail waveform and the licence line. Library tracks are licensed for use on flayr only: no audio URL or download is offered; they are applied to a video by flayr’s render pipeline. Kind: read. Scope: read. Endpoint: GET /api/v2/music/library. ### music_library_sections Get a live flayr library track’s sections (intro, lift, drop, breakdown, ending), BPM, beat offset and full waveform, to choose a clip start and length that land on a beat or section. 404 when the track is not live. Kind: read. Scope: read. Endpoint: GET /api/v2/music/library/{id}/sections. ### mercatus_store_connect Connects a Mercatus Liber store to a brand, the same as Connect > Store in the dashboard. Send `baseUrl` (the store's https Store API URL, e.g. https://shop.example.com/api/store/v1), `apiKey` (a Store API key from the store admin) and optionally `scopes` (default ["products:read"]; add "webhooks:manage" for live sync) and `brandId` (required on an account-wide connection). The store key is checked against the store before anything is saved, stored encrypted and never returned. Calling it again rotates the store key. Needs the explicit `stores:manage` scope plus `write`; the owner must be an owner or admin of the brand's organization. Audited against this connection. Kind: write. Scope: stores:manage. Endpoint: POST /api/v2/stores/mercatus/connect. ### mercatus_store_status The brand's connected Mercatus Liber store (URL, name, scopes and import state), or `store: null`. Never includes the store key. `brandId` is required on an account-wide connection. Needs the explicit `stores:manage` scope plus `write`. Kind: read. Scope: read. Endpoint: GET /api/v2/stores/mercatus/connect. ### mercatus_store_disconnect Disconnects the brand's Mercatus Liber store, the same as "Disconnect store" in the dashboard: removes the connection, its stored key and the imported products and collections (drafts are kept). Refuses a Shopify App Store connection. `brandId` is required on an account-wide connection. Needs the explicit `stores:manage` scope plus `write`. Confirm with the user first. Kind: destructive. Scope: stores:manage. Endpoint: DELETE /api/v2/stores/mercatus/connect. ### mercatus_store_import Imports products from the brand's connected Mercatus Liber store, the same as the dashboard's product picker. Send `productGids` (gid://mercatus/Product/<id> or the bare store product id, up to 300) to add those products and import them; send none to refresh every product already imported. Runs in the background; the dashboard's cooldowns and import-set cap apply (429 import_cooldown carries retryAfterMs). `brandId` is required on an account-wide connection. Needs the explicit `stores:manage` scope plus `write`. Kind: write. Scope: stores:manage. Endpoint: POST /api/v2/stores/mercatus/import. ### mercatus_store_products The brand's imported Mercatus Liber products (GID, title, handle, status, price range, image, variant count, import time), newest first, `limit` 1-100 per page with `cursor` paging, plus the import's state (`import.running`, last run). `brandId` is required on an account-wide connection. Needs the explicit `stores:manage` scope plus `write`. Kind: read. Scope: read. Endpoint: GET /api/v2/stores/mercatus/import. ### mercatus_store_promotions The promotions (discount codes) in the brand's connected Mercatus Liber store: id, code, kind, value, status (active or inactive), dates and redemptions. The store key must have been granted promotions:read. `brandId` is required on an account-wide connection. Needs the explicit `stores:manage` scope plus `write`. Kind: read. Scope: read. Endpoint: GET /api/v2/stores/mercatus/promotions. ### mercatus_store_promotion_create Creates a promotion in the brand's Mercatus Liber store, ALWAYS inactive (a draft no shopper can use). `kind` is "percentage" (`value` above 0, at most 100) or "fixed" (`value` in minor units, e.g. 500 = 5.00); optional `code` (3-40 letters, digits, - or _), `startsAt`, `endsAt`. The store key must have been granted promotions:write. `brandId` is required on an account-wide connection. Needs the explicit `stores:manage` scope plus `write`. Audited. Kind: write. Scope: stores:manage. Endpoint: POST /api/v2/stores/mercatus/promotions. ### mercatus_store_promotion_status Sets a Mercatus Liber store promotion's `status` to "active" (live: shoppers can use it) or "inactive". Nothing else about the promotion can be changed here. Confirm with the user before activating. The store key must have been granted promotions:write. `brandId` is required on an account-wide connection. Needs the explicit `stores:manage` scope plus `write`. Audited. Kind: write. Scope: stores:manage. Endpoint: PATCH /api/v2/stores/mercatus/promotions/{id}. --- Source: https://flayr.social/help/features/getting-started # Getting started The first steps every new account takes: set your brand voice, ask chat for a first caption and image, and connect a social account. The in-app Getting Started tutorial tracks these steps and rewards you when you finish. ## The first five steps 1. **Sign in.** This step completes itself on your first login. 2. **Set your brand voice** in Brand Intelligence: your tone, audience and key messages. 3. **Generate your first caption** in Chat. Ask for a caption about anything you sell or do. 4. **Generate your first image** in Chat. Ask for an image to go with it. 5. **Connect a social account** on the Connections page. New accounts can do this during the 14-day posting trial, no card needed. Your progress shows in the Getting Started tutorial. Finish every step and claim the reward. ## Overview The first steps every new account takes: set your brand voice, ask chat for a first caption and image, and connect a social account. The in-app Getting Started tutorial tracks these steps and rewards you when you finish. null 1. Sign in This step completes itself on your first login. 2. Set your brand voice in Brand Intelligence: your tone, audience and key messages. 3. Generate your first caption in Chat. Ask for a caption about anything you sell or do. 4. Generate your first image in Chat. Ask for an image to go with it. 5. Connect a social account on the Connections page. New accounts can do this during the 14-day posting trial, no card needed. ## flayr in two minutes: chat, studio, calendar, queues, workflows ## Meet Rockit, your guide to creating with Flayr ## flayr in two minutes --- Source: https://flayr.social/help/features/chat # Chat Create posts, captions, carousels, images and videos by describing what you want. Chat shows what each model costs in Embers before you run it, can research the web, and can plan first so you approve before anything is made. ## How to use it 1. Open **Chat** from the sidebar. 2. Describe what you want, for example "a 5-slide carousel about spring hours" or "three captions for this photo". 3. Pick a model. Each one shows its cost in Embers. 4. Review what chat made and send it to your library, the editor or the schedule. ## Tips - Attach files or images so chat can work from your own material. - Chat uses your brand voice from Brand Intelligence, so set that first. ## Create with chat Describe what you want and chat makes it: posts, captions, carousels, images and videos, in your brand voice. null 1. Open Chat Open **Chat** from the sidebar. 2. Describe what you want For example "a 5-slide carousel about spring hours" or "three captions for this photo". 3. Check the cost The flame badge next to the model shows the cost in Embers before you run it. 4. Keep what you like Use **Save to Library** under a reply, or **Post to Social** to publish it. ## Advanced chat Choose the models, have chat show you a plan before it spends Embers, run deep research, work from your own files, and branch a conversation to try another direction. null 1. Open the chat settings Choose **Show settings** in the chat header. **Output** sets the platform and an optional template, **Models** the text, image and video models, and **Brand** the brand voice and whether your logo goes on images. 2. Pick a model and check its cost Each model shows its cost as "~N Embers". A model your plan does not include shows "Requires" a plan and cannot be picked. 3. Choose Approve to see a plan first Under **Mode**, **Execute** runs straight away and **Approve** shows you a plan first. In Approve mode, choose **Approve** (with its Embers cost) to go ahead, or **Cancel**. 4. Run deep research Choose the **Research** chip above the message box, then write your question. Chat researches it before it answers. 5. Work from your own files Use the attach button: **Choose from Library**, or **Upload New** for images, videos, audio or a PDF. Attachments need a Pro plan. 6. Try another direction Under any reply, **Re-roll from here** starts a new branch from that point. Earlier chats are in **Chat Sessions**, with a search box. ## AI images Generate on-brand images from a prompt, in Chat or the image tools. The cost in Embers is shown before you generate. ## How to use it 1. In **Chat**, ask for an image, or attach one to edit. 2. Pick an image model and check its cost. 3. Save the result to your library or use it in a post. 1. In Chat, ask for an image, or attach one to edit. 2. Pick an image model and check its cost. 3. Save the result to your library or use it in a post. ## flayr demo: one idea in chat --- Source: https://flayr.social/help/features/hook-studio # Hook Studio Build a bank of hooks, bodies and calls to action for your brand by chatting. flayr asks only what it does not already know about your brand, then writes hooks you can star, edit or reject. Nothing is posted or scheduled. ## How to use it 1. Open **Ask** and pick **Make hooks with me**, or say "make hooks" in chat. 2. Answer a few questions about your offers and audience. Anything you save to your brand is shown first, on a card you approve. 3. Work through **Hooks**, **Bodies** and **Calls to action**. Star the ones you like, edit or reject the rest. 4. The summary shows how many pairs and combinations you have and an Embers estimate. ## Good to know - You can skip a step and come back later, on any device; your answers are kept. - Paid steps show their price in Embers before they run. - A body that names something not found on your site is marked unverified until you confirm it. ## Make a hook bank A guided chat that builds hooks, bodies and calls to action for one brand, in seven steps. You can skip any step and come back on any device. null 1. Interview flayr asks only what it does not already know about your brand and offers. Anything it would save to your brand shows first, on one card you approve. 2. Hooks Hooks come in batches from different angles. Star the ones you like, edit or reject the rest. Every line is checked for claims your brand cannot back up. 3. Bodies Pick what each hook leads into: a library video, a product or a short text. A body with no transcript is marked unverified until you confirm what it shows. 4. Calls to action Calls to action are built from your confirmed offers, and only point where a link is verified for that platform. 5. Summary A card with your hooks, bodies, calls to action, how many pairs they make and an Embers estimate. 6. Mix Choose which hooks go with which bodies. Mixing arrives with the Studio Mixer; until then the path ends at the summary and your bank is saved. 7. Preview Three sample combinations as text and a still image, before anything is rendered. ## The bank in Studio Studio → Hook Studio lists the active brand's hooks, bodies, calls to action and offers. Edit, star or retire any of them; nothing is deleted. In Basic, turn on Advanced in Studio to see the card. null 1. Start Start opens the guided chat. Each paid step shows its price in Embers before it runs; the text steps work on every plan. 2. Bank Edit a hook or call to action and the claims check runs again, with its findings under the line. Run claims check again re-checks without an edit. Retired lines stay in the bank but are no longer paired. 3. Offers An offer shows where its price comes from. A price entered by hand with a proof link can be verified: it is marked verified only when the page shows that price. Offers are also under Brand → Offers in Advanced. 4. Voice When voice mode is on for your account, you can answer the interview out loud; it drives the same steps. --- Source: https://flayr.social/help/features/brand-intelligence # Brand Intelligence Your brand profile: voice, audience, colors, logos and key messages. Every generator reads it, so content comes out on-brand. Each company or client brand keeps its own profile. ## How to use it 1. Open **Brand Intelligence** from the sidebar. 2. Fill in your voice, audience and messaging, or import them from your website. 3. Add your logo and brand colors. The sidebar shows which brand you are editing. Switch brands to edit another profile. ## Overview Your brand profile: voice, audience, colors, logos and key messages. Every generator reads it, so content comes out on-brand. Each company or client brand keeps its own profile. null 1. Open Brand Intelligence from the sidebar. 2. Fill in your voice, audience and messaging, or import them from your website. 3. Add your logo and brand colors. ## Areas Lanes inside one company, each with its own voice, colors, formats, calendar filter and case study. ## How to use it 1. Open your brand settings and add an area. 2. Give it its own voice and colors. 3. Filter the calendar by area. 1. Open your brand settings and add an area. 2. Give it its own voice and colors. 3. Filter the calendar by area. --- Source: https://flayr.social/help/features/connect-accounts # Connect social accounts Link the social accounts flayr posts to. Once connected, you can publish and schedule straight from flayr and see their analytics. New accounts get a 14-day posting trial for up to 3 connected accounts, no card needed. ## How to use it 1. Open **Connections**. 2. Pick a platform and sign in to it to approve flayr. 3. The account appears in the publish and schedule pickers. ## Connect an account Link the social accounts flayr posts to. flayr connects to 13 networks: Instagram, Facebook, TikTok, YouTube, X, LinkedIn, Threads, Bluesky, Pinterest, Google Business Profile, Telegram, Snapchat and Discord. Every new account gets a 14-day posting trial, no card needed: up to 3 connected accounts can post. After the trial, posting pauses until you choose a plan. Nothing is deleted. The bar at the top of Connections shows how many accounts you have used. null 1. Open Connections Open **Connections** from the sidebar. 2. Pick a platform Choose **Connect Account** on the platform card. If the button says **Requires** and a plan name instead, your trial has ended or your plan does not include posting: choose a plan to connect. 3. Sign in and approve flayr Sign in on the platform's own page and allow every permission it asks for. 4. Use it to publish The account appears in the publish and schedule pickers. 5. Add another account on the same platform Once one is connected, choose **Connect another ... account or Page** under that card. Each account counts toward your limit: 3 during the posting trial, then what your plan includes. At the limit, the bar offers **Buy more accounts** to people who can buy them. ## Instagram Connect your Instagram account so flayr can publish and schedule to it. You sign in on Instagram itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Instagram card Find the **Instagram** card and choose **Connect Account**. 3. Sign in to Instagram and allow flayr Instagram opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected Instagram!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Facebook Connect a Facebook Page so flayr can publish and schedule to it. After you sign in, flayr asks which of your Pages to connect. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Facebook card Find the **Facebook** card and choose **Connect Account**. 3. Sign in to Facebook and allow flayr Facebook opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Select the Page to connect Back in flayr, **Select Facebook Page** lists the Pages you manage. Pick one (a single Page is picked for you) and choose **Connect Facebook Page**. If no Page is listed, check you are an admin of the Page on Facebook, then use **Back to Connect** and try again. 5. Connect another Page To add a second Page, choose **Connect another Facebook account or Page** under the card. ## TikTok Connect your TikTok account so flayr can publish and schedule to it. You sign in on TikTok itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the TikTok card Find the **TikTok** card and choose **Connect Account**. 3. Sign in to TikTok and allow flayr TikTok opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected TikTok!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## YouTube Connect your YouTube account so flayr can publish and schedule to it. You sign in on YouTube itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the YouTube card Find the **YouTube** card and choose **Connect Account**. 3. Sign in to YouTube and allow flayr YouTube opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected YouTube!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## X Connect your X account so flayr can publish and schedule to it. You sign in on X itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the X card Find the **X** card and choose **Connect Account**. 3. Sign in to X and allow flayr X opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected X!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## LinkedIn Connect your LinkedIn account so flayr can publish and schedule to it. You sign in on LinkedIn itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the LinkedIn card Find the **LinkedIn** card and choose **Connect Account**. 3. Sign in to LinkedIn and allow flayr LinkedIn opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected LinkedIn!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Threads Connect your Threads account so flayr can publish and schedule to it. You sign in on Threads itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Threads card Find the **Threads** card and choose **Connect Account**. 3. Sign in to Threads and allow flayr Threads opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected Threads!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Bluesky Connect your Bluesky account so flayr can publish and schedule to it. You sign in on Bluesky itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Bluesky card Find the **Bluesky** card and choose **Connect Account**. 3. Sign in to Bluesky and allow flayr Bluesky opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected Bluesky!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Pinterest Connect your Pinterest account so flayr can publish and schedule to it. You sign in on Pinterest itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Pinterest card Find the **Pinterest** card and choose **Connect Account**. 3. Sign in to Pinterest and allow flayr Pinterest opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected Pinterest!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Google Business Profile Connect your Google Business Profile account so flayr can publish and schedule to it. You sign in on Google Business Profile itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Google Business Profile card Find the **Google Business Profile** card and choose **Connect Account**. 3. Sign in to Google Business Profile and allow flayr Google Business Profile opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected Google Business Profile!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Telegram Connect your Telegram account so flayr can publish and schedule to it. You sign in on Telegram itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Telegram card Find the **Telegram** card and choose **Connect Account**. 3. Sign in to Telegram and allow flayr Telegram opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected Telegram!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Snapchat Connect your Snapchat account so flayr can publish and schedule to it. You sign in on Snapchat itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Snapchat card Find the **Snapchat** card and choose **Connect Account**. 3. Sign in to Snapchat and allow flayr Snapchat opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected Snapchat!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Discord Connect your Discord account so flayr can publish and schedule to it. You sign in on Discord itself. null 1. Open Connections Open **Connections** from the sidebar. 2. Choose Connect Account on the Discord card Find the **Discord** card and choose **Connect Account**. 3. Sign in to Discord and allow flayr Discord opens its own sign-in page. Sign in to the account you want flayr to post to and allow every permission it asks for. If you skip one, flayr asks you to connect again. 4. Check the card says Connected You come back to Connections with "Successfully connected Discord!". The card now shows the account name and "Connected to this workspace", and the account appears in the publish and schedule pickers. ## Reconnect or disconnect Platforms sometimes sign flayr out. A card that says "Reconnect needed" stops posting until you reconnect it. Reconnecting the same account never counts as another account. null 1. Open Connections Open **Connections** from the sidebar. 2. Reconnect an account On a card that says **Reconnect needed** (or "Reconnect to avoid disconnection"), choose **Reconnect** and sign in to the same account again. 3. Disconnect an account Choose **Disconnect** on the card and confirm. flayr stops posting to it. ## Shopify Link your Shopify store so flayr can make posts from your products. ## How to use it New accounts can do this during the 14-day posting trial, no card needed. Each store uses one account from the same allowance as social accounts. Connections shows your current allowance and an upgrade link when it is full. 1. Open Connections → Content Sources and connect your Shopify or Mercatus store. 2. Choose from your store in the product picker or campaign builder. Generated content waits for your approval. 1. Open Connections → Content Sources and connect your Shopify or Mercatus store. 2. Choose from your store in the product picker or campaign builder. Generated content waits for your approval. --- Source: https://flayr.social/help/features/embers # Embers Embers are only for AI. Posting and scheduling never use them, and AI you run on your own key uses none. Your plan adds Embers every month, and unused monthly Embers carry over for the number of months your plan allows. Embers you buy or earn as rewards never expire. Each AI action shows its cost before you run it. ## What Embers are for Embers are just a way for you to use AI features without bankrupting us. Posting and other actions are free. X posts with a link use Embers, because X charges for them. If you bring your own AI key, Embers aren’t spent. To use the AI on your own videos and images, bring your own key or use your Embers. - Posting, scheduling, saving drafts and uploading your own photos and videos are free. The one exception: an X post with a link uses Embers, because X charges for it. - AI uses Embers: writing, images, video, voice. Each one shows "This uses X Embers · you have Y" before you run it. - With your own AI key (**Settings → AI keys**), the models under "Your keys" use no Embers. Your provider bills you. ## Where to see them - Your balance is in the sidebar and on the **Rewards** page. - Every AI action shows its cost in Embers before you run it. ## How to earn more - Leave a review on **My Reviews**. Approved reviews earn Embers. - Claim the rewards for the achievements you unlock on the **Achievements** tab. - Submit a tutorial video for a feature in the help center. Approved videos can earn Embers. ## Your Embers Embers are only for AI. Posting and scheduling never use them. Your plan adds Embers every month, and each AI action shows its cost before you run it. null 1. See your balance Your balance is in the sidebar and on the **Embers** tab of **Rewards**, with your history. 2. Check a cost before you run Each AI action shows "This uses X Embers · you have Y" before you run it. Posting never uses Embers. 3. Use your own AI key In **Settings → AI keys**, save your own key. Models under "Your keys" use no Embers; your provider bills you. 4. Buy more On the **Embers** tab, choose **Buy more Embers**. Embers you buy never expire. ## Earn Embers Earn Embers by reviewing flayr, claiming achievements and recording tutorial videos for the help center. Embers you earn as rewards never expire. null 1. See the ways to earn Open **Rewards** and look under **Earn more** on the **Embers** tab. 2. Leave a review Open **My Reviews** and fill in **Leave a Review, Earn 500 Embers**. The Embers arrive when the review is approved. 3. Claim achievements On the **Achievements** tab, claim each reward you unlock before its claim window closes. 4. Record a tutorial video On any feature in the help center, choose **Submit** on an empty video slot and send your walkthrough. Approved videos can earn Embers. ## Rewards, referrals and community One page for your Embers, referral link, achievements and the community: polls and the ideas board. Share your referral link and earn when friends sign up. ## How to use it 1. Open **Rewards**. 2. Copy your referral link from the Referrals tab and share it. 3. Vote in polls and post ideas on the Community tab. 4. Check your badges on the Achievements tab. 1. Open Rewards. 2. Copy your referral link from the Referrals tab and share it. 3. Vote in polls and post ideas on the Community tab. 4. Check your badges on the Achievements tab. ## My Reviews Rate flayr and tell us how it is going. Reviews are a private rating signal; you choose which ones are public, and you can delete any of them. ## How to use it 1. Open **My Reviews**. 2. Under **Leave a Review**, pick a star rating and, if you like, write up to 1,000 characters. 3. Choose **Submit Review**. New reviews start out private. 4. Under **Your Reviews**, use the eye button to make a review public or private, or the bin button to delete it. ## Good to know - When it is offered, a public review with at least 20 characters of text can be shared as a testimonial: tick the box and choose **Share**. It is shown only after review. - Deleting a review cannot be undone. 1. Open My Reviews. 2. Under Leave a Review, pick a star rating and, if you like, write up to 1,000 characters. 3. Choose Submit Review. New reviews start out private. 4. Under Your Reviews, use the eye button to make a review public or private, or the bin button to delete it. --- Source: https://flayr.social/help/features/post-studio # Post Studio Every editor in one place: posts, carousels, stories, video compose, the video creator, voice and templates. Start here when you know the format you want. ## How to use it 1. Open **Studio** from the sidebar. 2. Pick the format you want to make. 3. Finished pieces land in your library and can go to Pending or the schedule. ## Overview Every editor in one place: posts, carousels, stories, video compose, the video creator, voice and templates. Start here when you know the format you want. null 1. Open Studio from the sidebar. 2. Pick the format you want to make. 3. Finished pieces land in your library and can go to Pending or the schedule. ## Post editor Write and polish a single post with AI help: captions, hooks and hashtags tuned for each platform, with a preview of how it will look. ## How to use it 1. Open **Studio** and pick the post editor. 2. Write or generate your caption and add media. 3. Pick platforms and check each preview. 4. Send it to Pending, schedule it or post it. 1. Open Studio and pick the post editor. 2. Write or generate your caption and add media. 3. Pick platforms and check each preview. 4. Send it to Pending, schedule it or post it. ## Carousels Build multi-slide carousels from a topic: flayr plans the slides, makes the images and writes one caption for the whole set. Edit any slide before you post. ## How to use it 1. Ask Chat for "a 5-slide carousel about …", or open the carousel editor in **Studio**. 2. Review the slide plan, then generate. 3. Edit slide text or images, then schedule or post. 1. Ask Chat for "a 5-slide carousel about …", or open the carousel editor in Studio. 2. Review the slide plan, then generate. 3. Edit slide text or images, then schedule or post. ## Hashtag generator Get hashtag suggestions for a topic or caption, tuned to the platform you are posting on. ## How to use it 1. Open the **Hashtag Generator**. 2. Enter your topic or paste your caption. 3. Copy the hashtags you want into your post. 1. Open the Hashtag Generator. 2. Enter your topic or paste your caption. 3. Copy the hashtags you want into your post. ## Templates Start from a template instead of a blank page: Record Room, Poem, a segment ad, a weekly offer campaign or a parody video. ## How to use it 1. Open **Templates** from Studio, or browse the [templates gallery](/help/templates). 2. Read what each one needs and what you get, then choose **Use this template**. 3. Bring your own words. Every template leaves drafts for you to approve. Each template in the gallery has a walkthrough video and campaigns built with it. 1. Open Templates from Studio, or browse the [templates gallery](/help/templates). 2. Read what each one needs and what you get, then choose Use this template. 3. Bring your own words. Every template leaves drafts for you to approve. ## Story editor Design Instagram Stories on a canvas: add text, images and a background, drop in visual stickers such as a poll or countdown, and save the result to your Library as an Instagram draft. ## How to use it 1. Open **Studio** and pick **Story editor**, or pick **Story Builder** on the Create page. 2. Under **Add Layer**, add **Text**, an **Image** or a **Background Image**. 3. Under **Stickers**, add a **Poll**, **Question**, **Countdown**, **Hashtag**, **Mention**, **Link** or **Emoji Slider**. 4. Set the background to a solid color or a gradient. 5. Select a layer on the canvas to change it in the side panel, or choose **Delete layer** to remove it. 6. Choose **Save to Library**. The story is saved as an image draft for Instagram. ## Good to know - Stickers look real but are not interactive. Add interactive elements in the Instagram app. - If your plan does not include Interactive Stories, the editor shows an upgrade option instead. 1. Open Studio and pick Story editor, or pick Story Builder on the Create page. 2. Under Add Layer, add Text, an Image or a Background Image. 3. Under Stickers, add a Poll, Question, Countdown, Hashtag, Mention, Link or Emoji Slider. 4. Set the background to a solid color or a gradient. 5. Select a layer on the canvas to change it in the side panel, or choose Delete layer to remove it. 6. Choose Save to Library. The story is saved as an image draft for Instagram. --- Source: https://flayr.social/help/features/video-creator # Video creator Generate short AI videos from a prompt. Pick a model and length; the cost in Embers is shown before you generate, and finished clips land in your library. ## How to use it 1. Go to **/video-creator**. It is in the Create section of the classic sidebar; Studio has no card for it, so with the new navigation open the address directly. 2. Describe the shot, then pick a model and length. 3. Check the Embers cost and generate. 4. The finished video lands in your library. ## Overview Generate short AI videos from a prompt. Pick a model and length; the cost in Embers is shown before you generate, and finished clips land in your library. null 1. Go to /video-creator. It is in the Create section of the classic sidebar; Studio has no card for it, so with the new navigation open the address directly. 2. Describe the shot, then pick a model and length. 3. Check the Embers cost and generate. 4. The finished video lands in your library. ## Compose video Make one short video for a platform, two ways: Generate an AI clip of 2 to 30 seconds from a prompt, or Upload a video you already have and reformat it for the platform with a text overlay. ## How to use it 1. Open **Video composer** from Studio. 2. Pick a mode: - **Generate**: describe the clip and set its length (2 to 30 seconds). The Embers cost shows before you generate. - **Upload**: paste the link to a video you already have. 3. Pick the platform, and add the text overlay you want on the video. 4. Generate or compose. A generated clip can go straight on to Upload to get its overlay. 1. Open Video composer from Studio. 2. Pick a mode: - **Generate**: describe the clip and set its length (2 to 30 seconds). The Embers cost shows before you generate. - **Upload**: paste the link to a video you already have. 3. Pick the platform, and add the text overlay you want on the video. 4. Generate or compose. A generated clip can go straight on to Upload to get its overlay. ## Shot lists Build a video from AI shots, and remake one shot without remaking the rest. ## How to use it 1. Start a shot list for your video. 2. Generate each shot. 3. Redo any single shot you do not like, then assemble the video. 1. Start a shot list for your video. 2. Generate each shot. 3. Redo any single shot you do not like, then assemble the video. --- Source: https://flayr.social/help/features/voice-studio # Voice studio Turn scripts into voiceovers with stock voices on every plan. Voiceovers can be used in your videos. ## How to use it 1. Open **Voice Studio** from Studio. 2. Write or generate a script. 3. Pick a stock voice. 4. Generate the audio and use it in a video. To speak in your own voice, see **Voice cloning**. ## Overview Turn scripts into voiceovers with stock voices on every plan. Voiceovers can be used in your videos. null 1. Open Voice Studio from Studio. 2. Write or generate a script. 3. Pick a stock voice. 4. Generate the audio and use it in a video. ## Voice cloning Clone your own voice in Voice Studio from a recording or an upload, then generate voiceovers that sound like you. ## How to use it 1. Open **Voice Studio** from Studio. 2. Record yourself reading the script, or upload a clean sample. 3. Give the voice a name and create the clone. 4. Pick your clone as the voice when you generate speech. 1. Open Voice Studio from Studio. 2. Record yourself reading the script, or upload a clean sample. 3. Give the voice a name and create the clone. 4. Pick your clone as the voice when you generate speech. ## Voice clone training Make a voice clone sound more like you. Record guided takes in different styles, build candidate voices, compare them in blind A/B rounds, and choose which version becomes your voice. Nothing switches over without your click. ## How to use it 1. Make a voice clone in **Voice Studio** first, then choose **Train this voice** on it. 2. Record that the voice is yours and that you agree to training. Training does not start without this. 3. Record the planned takes. Each take is checked; a take that cannot be used tells you why. You can also import longer recordings of your own voice. 4. Watch the meter: at 5 usable minutes you can **Build candidates**, which speaks the same lines in each new voice. 5. Open **Rate your voices** and run a blind round: pick the better voice in each pair without knowing which is which. 6. When the round is finished, see the results and choose **Make this my voice** on the one you want. You can roll back to an earlier version later. ## Good to know - Some takes are kept back as anchors: they are never used for training, only as the real you in blind tests. - At 20 usable minutes a fuller fine-tune unlocks. - Auditions cost Embers at your cloned voice rate, and imports cost Embers per started hour of audio. A build that fails before its auditions charges nothing, and a failed or cancelled job is refunded. 1. Make a voice clone in Voice Studio first, then choose Train this voice on it. 2. Record that the voice is yours and that you agree to training. Training does not start without this. 3. Record the planned takes. Each take is checked; a take that cannot be used tells you why. You can also import longer recordings of your own voice. 4. Watch the meter: at 5 usable minutes you can Build candidates, which speaks the same lines in each new voice. 5. Open Rate your voices and run a blind round: pick the better voice in each pair without knowing which is which. 6. When the round is finished, see the results and choose Make this my voice on the one you want. You can roll back to an earlier version later. ## Clone your voice in flayr's Voice Studio ## Our first voice clone --- Source: https://flayr.social/help/features/library # Library Everything you upload or generate in one place: images, videos, documents and drafts. Label and filter it, import from Google Drive, and send any item to a post or queue. ## How to use it 1. Open **Library** from the sidebar. 2. Upload files, or import them from Google Drive in Library settings. 3. Add labels to keep things organized, and filter by label. 4. Open an item to post it, schedule it or add it to a queue. ## Overview Everything you upload or generate in one place: images, videos, documents and drafts. Label and filter it, import from Google Drive, and send any item to a post or queue. null 1. Open Library from the sidebar. 2. Upload files, or import them from Google Drive in Library settings. 3. Add labels to keep things organized, and filter by label. 4. Open an item to post it, schedule it or add it to a queue. ## Opus Clip integration Connect Opus Clip with your Opus API key, then send a video from your library to Opus, or link an existing Opus project and import its clips. The clips land in your library, ready to schedule. ## How to use it 1. Go to **Settings → Integrations** and connect Opus Clip with your Opus API key. 2. In your library, send a video to Opus, or link an existing Opus project by its ID. 3. Import the clips. They land in your library, ready to schedule. 1. Go to Settings → Integrations and connect Opus Clip with your Opus API key. 2. In your library, send a video to Opus, or link an existing Opus project by its ID. 3. Import the clips. They land in your library, ready to schedule. ## Auto clips Cut a long video into captioned vertical clips. The clips are saved as library drafts, and the work is paid in Embers. ## How to use it 1. Pick a long video in your library. 2. Start auto clips and check the Embers cost. 3. Review the clips in your library drafts. 1. Pick a long video in your library. 2. Start auto clips and check the Embers cost. 3. Review the clips in your library drafts. ## Asset Library Generated content, uploads, reusable templates, stock media and chats in one place, split into tabs. It is the same library as Library on the new navigation. ## How to use it 1. Open **Asset Library** from the sidebar. 2. Pick a tab: **Generated**, **Uploaded**, **Opus Clip**, **Templates**, **Stock**, **Chats** or **HyperFrames**. 3. To add your own files, open **Uploaded** and choose **Upload Files**. 4. To find stock media, open **Stock**, search free photos or videos from Pexels and Pixabay, and save the ones you want. They appear under **Your saved stock**. 5. Use the settings button next to the title to connect cloud storage such as Google Drive. ## Good to know - **Templates** shows the render templates your workflows can use, and your saved content templates. - Saved stock items can be posted or re-used like any other library item. 1. Open Asset Library from the sidebar. 2. Pick a tab: Generated, Uploaded, Opus Clip, Templates, Stock, Chats or HyperFrames. 3. To add your own files, open Uploaded and choose Upload Files. 4. To find stock media, open Stock, search free photos or videos from Pexels and Pixabay, and save the ones you want. They appear under **Your saved stock**. 5. Use the settings button next to the title to connect cloud storage such as Google Drive. ## Auto clips in flayr: turn one long video into captioned shorts ## Pull your Opus Clip clips straight into flayr ## Stop paying for a separate clipping tool ## Drop in a long video ## One Video, Three Useful Posts --- Source: https://flayr.social/help/features/review-and-approvals # Review and approvals Everything between "made" and "posted": Pending holds what waits to go out, the review queue collects what needs a second look, and approval rules decide who signs off before anything posts. ## How to use it 1. Open **Pending** from the sidebar. 2. Use **Needs review** to approve or edit items waiting on you. 3. Use **All content** to find anything you have prepared. ## Pending and review Pending is where content waits before it goes out. Its "Needs review" tab is the review queue: approve, edit or send back anything that needs a second look. null 1. Open Pending Open **Pending** from the sidebar. 2. Approve or edit what waits on you Use **Needs review** to approve or edit items waiting on you. 3. Find anything you prepared Use **All content** to find anything you have prepared. ## Approval workflows Set up multi-step approvals so content is signed off by the right people before it goes out. ## How to use it 1. Open **Settings → Approval Workflows**. 2. Create a workflow and add the reviewers for each step. 3. Content that needs approval waits in Pending → Needs review. 1. Open Settings → Approval Workflows. 2. Create a workflow and add the reviewers for each step. 3. Content that needs approval waits in Pending → Needs review. ## Review queue Scheduled posts to sign off, and workflows waiting on your decision before they can continue, on one page. Links in review emails and notifications open it. ## How to use it 1. Open **Review queue** from the sidebar, or follow the link in a review email or notification. 2. Under **Scheduled posts needing review**, oldest first, select a post to open its preview. 3. Add a note if you like, then choose **Looks good**, **Edit** or **Hold**. Holding asks you to confirm with **Hold post**. 4. Under **Workflow approvals**, choose **Approve** to let the workflow continue, or **Reject**. 5. When you reject, add an optional reason, then choose **Reject**, **Reject & edit** or **Reject & delete**. ## Good to know - Rejecting a workflow approval stops that workflow run. - **Reject & delete** deletes the content for everyone and cannot be undone. - On the new navigation, this page opens Pending → Needs review instead. 1. Open Review queue from the sidebar, or follow the link in a review email or notification. 2. Under Scheduled posts needing review, oldest first, select a post to open its preview. 3. Add a note if you like, then choose Looks good, Edit or Hold. Holding asks you to confirm with **Hold post**. 4. Under Workflow approvals, choose Approve to let the workflow continue, or Reject. 5. When you reject, add an optional reason, then choose Reject, Reject & edit or Reject & delete. --- Source: https://flayr.social/help/features/scheduling # Scheduling and the calendar Plan posts on a calendar. Drag a draft onto a day and pick a time, see every brand at once or one at a time, and turn suggested posting times on or off. Upcoming, Queues and Reminders sit in the same tab row. ## How to use it 1. Open **Schedule**. Drafts are on one side, the calendar on the other. 2. Drag a draft onto a day and pick a time. If it has no platforms yet, flayr asks for them. 3. Use the brand filter to see one brand or all of them. 4. Check **Upcoming** for everything booked. ## Overview Plan posts on a calendar. Drag a draft onto a day and pick a time, see every brand at once or one at a time, and turn suggested posting times on or off. Upcoming, Queues and Reminders sit in the same tab row. null 1. Open Schedule. Drafts are on one side, the calendar on the other. 2. Drag a draft onto a day and pick a time. If it has no platforms yet, flayr asks for them. 3. Use the brand filter to see one brand or all of them. 4. Check Upcoming for everything booked. ## Posting queues A queue posts from a pile of content on a repeating schedule, for example one post a day to YouTube Shorts. Drag new content in and the queue keeps running; the more you add, the longer it goes. ## How to use it 1. Open **Schedule → Queues** and create a queue. 2. Pick the accounts and the posting slots, for example once a day. 3. Drag content from your library into the queue. 4. The queue books each item into the next free slot. 1. Open Schedule → Queues and create a queue. 2. Pick the accounts and the posting slots, for example once a day. 3. Drag content from your library into the queue. 4. The queue books each item into the next free slot. ## Direct posting Publish straight to your connected accounts from flayr, now or at a scheduled time. Posting is included in the 14-day posting trial and on paid plans, within each platform's own limits. ## How to use it 1. Connect an account on the **Connections** page. 2. From any finished piece, pick accounts and post now or schedule it. 3. If a post fails, flayr shows why and lets you retry. 1. Connect an account on the Connections page. 2. From any finished piece, pick accounts and post now or schedule it. 3. If a post fails, flayr shows why and lets you retry. ## Scheduling in flayr: drag, drop, and let the queue run ## I drag in a print, flayr posts one every day ## Every profile on one calendar --- Source: https://flayr.social/help/features/ads # Ads Run and boost ad campaigns from flayr for the ad accounts you connect, per company. ## How to use it 1. Open **Ads** and connect an ad account. 2. Create a campaign or boost a post. 3. Track spend and results on the same page. ## Overview Run and boost ad campaigns from flayr for the ad accounts you connect, per company. null 1. Open Ads and connect an ad account. 2. Create a campaign or boost a post. 3. Track spend and results on the same page. --- Source: https://flayr.social/help/features/workflows # Workflows Automate multi-step work such as cross-posting. Start from a template or build your own: every step has a trigger, settings, and inputs and outputs, and variables pass from one step to the next. An approval step can pause a run until someone signs off. ## How to use it 1. Open **Workflows** and start from a template, such as cross-platform sync, or a blank workflow. 2. Add steps. An AI text step can write a caption from the data of an earlier step. 3. Bind variables from one step into the next. 4. Run it once to test, then turn it on. ## Build a workflow A workflow is a chain of steps that starts on a trigger. Variables pass from one step to the next, and an Approval Gate step can pause a run until someone signs off. null 1. Open Workflows Open **Workflows**, then choose **Templates** to start from a ready-made workflow, or **New Workflow** for a blank one. 2. Add steps Drag steps from the palette. An AI text step can write a caption from the data of an earlier step. 3. Pass data between steps Bind variables from one step into the next. 4. Add an approval if you want one An **Approval Gate** step pauses the run until the **Approver** you pick approves it. It needs a Standard plan or higher. 5. Test, then turn it on Choose **Test** and **Run all** to try it, or **Run Once**. Tests run for real, so a publish step posts. When it works, choose **Activate**. ## Triggers The trigger is the first step: it decides when a workflow runs. Run it on a schedule, on demand, from a webhook, when a file is added, on a keyword, on a new follower, and more. null 1. Open the Triggers group In the workflow editor, open the palette and find the **Triggers** group. 2. Pick when it runs **Schedule** runs on a timetable, **Manual** on demand, **Webhook** when something sends it an HTTP POST. **Media Added** runs when an uploaded file name starts with the prefix you set, **Keyword Trigger** on the keywords you list, and **New Follower**, **New Event**, **Calendar Event** and **On Login** on those events. 3. Set a schedule For **Schedule**, choose **Run this workflow** every day, every weekday, once a week or once a month, then the time and time zone. **Advanced schedule** takes a cron expression. 4. Copy the webhook URL For **Webhook**, copy the **Webhook URL** shown on the step into the service that will call it. 5. Turn it on A trigger only fires once the workflow is active: choose **Activate**. ## Templates Ready-made workflows you install and change: content pipelines, cross-platform sync, photo to post, comment growth, approval flows and more. null 1. Open the templates Open **Workflows** and choose **Templates**. 2. Filter by what you need Use the chips (**Content**, **Cross-Platform**, **Analytics**, **CRM**, **Growth**) to narrow the list. Each card shows the plan it needs. 3. Install one Choose **Use this template**. flayr copies it into your workflows and opens it in the editor. 4. Make it yours Change the steps and settings, test it, then choose **Activate**. ## Automation One place for all your automations. The Home tab sorts your workflows into what needs attention, what is running, drafts ready to turn on and templates to start from; the other tabs open Workflows, Sequences, Auto-respond and Broadcasts. ## How to use it 1. Open **Automation** from the sidebar. 2. On **Home**, check **Needs attention** first: these are active automations whose last run failed. Choose **Resolve** to open the workflow. 3. Under **Recommended**, choose **Activate** on a draft to turn it on. 4. Under **Templates**, choose **View** to start from a pre-built automation. 5. Use the **Workflows**, **Sequences**, **Auto-respond** (keyword auto-replies, formerly Growth) and **Broadcasts** tabs to build and manage each kind of automation. ## Good to know - **Active** lists every enabled automation, including any that need attention. - Sequences, Auto-respond and Broadcasts only show as tabs when they are available to you. - If automated scheduling is turned off, an activated scheduled workflow will not fire until scheduling is back on. Automation tells you when that is the case. - Automation is part of the new navigation. On the classic navigation, open **Workflows** instead. 1. Open Automation from the sidebar. 2. On Home, check Needs attention first: these are active automations whose last run failed. Choose **Resolve** to open the workflow. 3. Under Recommended, choose Activate on a draft to turn it on. 4. Under Templates, choose View to start from a pre-built automation. 5. Use the Workflows, Sequences, Auto-respond (keyword auto-replies, formerly Growth) and Broadcasts tabs to build and manage each kind of automation. ## A reusable template for consistent content ## Automating cross-posting with flayr workflows (quick walkthrough) ## Flayr Workflows: Simple Posts to Advanced Content Automation ## Prepare photos before writing a post ## Start simple and grow your workflow --- Source: https://flayr.social/help/features/analytics # Analytics and insights See how your posts perform: engagement, reach, follower growth and the best times to post, across your connected accounts. ## How to use it 1. Open **Insights** (or Analytics). 2. Pick a date range and the accounts to compare. 3. Open a post to see its numbers. ## Overview See how your posts perform: engagement, reach, follower growth and the best times to post, across your connected accounts. null 1. Open Insights (or Analytics). 2. Pick a date range and the accounts to compare. 3. Open a post to see its numbers. ## Competitor benchmarking Track competitor accounts and compare their content and results with yours. ## How to use it 1. Open **Benchmarks**. 2. Add the competitor accounts you want to track. 3. Compare their posting and engagement with yours. 1. Open Benchmarks. 2. Add the competitor accounts you want to track. 3. Compare their posting and engagement with yours. ## Advanced insights Formulas, funnels, flayr events, CSV export, weekly dashboard emails and shareable client links. ## How to use it 1. Open **Insights** and create a dashboard. 2. Add formulas or funnels. 3. Share a client link or subscribe to the weekly email. 1. Open Insights and create a dashboard. 2. Add formulas or funnels. 3. Share a client link or subscribe to the weekly email. --- Source: https://flayr.social/help/features/inbox # Inbox Read and answer comments and messages from your connected accounts in one place. ## How to use it 1. Open **Inbox**. 2. Filter by account or platform. 3. Reply without leaving flayr. ## Overview Read and answer comments and messages from your connected accounts in one place. null 1. Open Inbox. 2. Filter by account or platform. 3. Reply without leaving flayr. ## Auto-replies Reply automatically when someone comments with a keyword you choose. A trigger can post a public reply, send a private DM, or both, and shows how often it fired. ## How to use it 1. Open **Growth** and choose **New Trigger**. 2. Give it a name and the keywords to listen for, separated by commas. 3. Write the comment reply, the DM, or both. Use {{name}} to add the person's name. 4. Save it. Use the power button to pause or turn a trigger back on. 5. Check **Recent Activity** to see who triggered it and what was sent. ## Good to know - Triggers fire on comments and messages your connected accounts receive, and replies go out from that account, so connect your accounts first. - A keyword matches when the comment contains it. 1. Open Growth and choose New Trigger. 2. Give it a name and the keywords to listen for, separated by commas. 3. Write the comment reply, the DM, or both. Use {{name}} to add the person's name. 4. Save it. Use the power button to pause or turn a trigger back on. 5. Check Recent Activity to see who triggered it and what was sent. ## Broadcasts Send one message to your contacts at once. A broadcast goes as a direct message to the contacts who are still subscribed, and shows how many were sent and how many failed. ## How to use it 1. Open **Broadcasts** and create a broadcast. 2. Give it a name and write the message. 3. Choose **Send** on the broadcast when you are ready. 4. Once it is done, the broadcast shows how many messages were delivered and how many failed. ## Good to know - Only contacts who are still subscribed get the broadcast. A contact with no conversation to reply into counts as failed. 1. Open Broadcasts and create a broadcast. 2. Give it a name and write the message. 3. Choose Send on the broadcast when you are ready. 4. Once it is done, the broadcast shows how many messages were delivered and how many failed. ## Sequences Drip campaigns that nurture contacts over time. A sequence is a list of steps with waits in between: send a message, add or remove a tag, check a condition, call a webhook or leave an internal note. ## How to use it 1. Open **Sequences** and create a sequence. Give it a name and, if you like, a description. 2. Add steps. For each one, set how long to wait before it and what it does. 3. Save the sequence. 4. Enroll contacts with the **Enroll in Sequence** step in a workflow. 5. Expand a sequence to see its enrollments, and pause, resume or cancel any of them. 1. Open Sequences and create a sequence. Give it a name and, if you like, a description. 2. Add steps. For each one, set how long to wait before it and what it does. 3. Save the sequence. 4. Enroll contacts with the Enroll in Sequence step in a workflow. 5. Expand a sequence to see its enrollments, and pause, resume or cancel any of them. ## Contacts The people who comment on or message your connected accounts, in one list. Search them, filter by platform, see their tags and open anyone for notes, tags and activity. Broadcasts and sequences send to these contacts. ## How to use it 1. Open **Contacts**. People are added when they comment on or message your connected accounts. 2. Search by name, or filter by platform. 3. Open a contact to see their activity and custom fields, add notes and add or remove tags. ## Good to know - Contacts marked Unsubscribed do not get broadcasts. 1. Open Contacts. People are added when they comment on or message your connected accounts. 2. Search by name, or filter by platform. 3. Open a contact to see their activity and custom fields, add notes and add or remove tags. ## Flayr Sequences: Build a Simple Drip Campaign ## Build a drip campaign from a template ## Write the first message in a drip campaign ## Give drip-campaign follow-ups a purpose ## How waits in a drip campaign add up --- Source: https://flayr.social/help/features/organizations-and-teams # Organizations and teams Work as a team: an organization shares brands, content and one Embers pool across its members. Invite teammates and switch between your workspaces. ## How to use it 1. Open **Settings → Organization**. 2. Invite teammates by email. 3. Switch workspaces from the workspace picker. ## Overview Work as a team: an organization shares brands, content and one Embers pool across its members. Invite teammates and switch between your workspaces. null 1. Open Settings → Organization. 2. Invite teammates by email. 3. Switch workspaces from the workspace picker. --- Source: https://flayr.social/help/features/client-workspaces # Client workspaces Agencies keep each client separate: their own brand profile, connected accounts, content and calendar. ## How to use it 1. Open **Clients** and add a client. 2. Switch to the client to set up their brand and accounts. 3. Everything you make there stays in that client. ## Overview Agencies keep each client separate: their own brand profile, connected accounts, content and calendar. null 1. Open Clients and add a client. 2. Switch to the client to set up their brand and accounts. 3. Everything you make there stays in that client. --- Source: https://flayr.social/help/features/developer-api # API, webhooks and MCP Connect flayr to your own tools: create API keys, watch usage, manage webhooks and connect the MCP server. The public API reference is at /docs. ## How to use it 1. Open **Developers**. 2. Create an API key and keep it somewhere safe. 3. Read the API reference at [/docs](/docs). 4. Add a webhook to hear about events as they happen. ## Overview Connect flayr to your own tools: create API keys, watch usage, manage webhooks and connect the MCP server. The public API reference is at /docs. null 1. Open Developers. 2. Create an API key and keep it somewhere safe. 3. Read the API reference at [/docs](/docs). 4. Add a webhook to hear about events as they happen. ## Your own AI keys Save your own Gemini or Anthropic key and run chat and image generation on it. Calls on your key cost 0 Embers; your provider bills you directly. ## How to use it 1. Go to **Settings → AI keys**, paste the key and save. flayr checks it with one free "list models" call first. 2. Models on your key appear in the pickers in their own "Your keys · 0 Embers" group. 3. Pick one of them whenever you want to run on your key. flayr never switches you over by itself. ## Good to know - Carousels, workflows, video, voice, the API and other flayr pipelines always run on flayr and cost Embers. - If your key fails, nothing is generated and no Embers are charged. - The key is encrypted; flayr only ever shows its last 4 characters. 1. Go to Settings → AI keys, paste the key and save. flayr checks it with one free "list models" call first. 2. Models on your key appear in the pickers in their own "Your keys · 0 Embers" group. 3. Pick one of them whenever you want to run on your key. flayr never switches you over by itself. ## Connect Claude Code (or any agent) to flayr with scoped API keys ## Make a scoped API key for your agent ## Agents draft. Humans approve. --- Source: https://flayr.social/help/features/campaign-builder # Campaign builder Plan a sale, a launch or a holiday push such as Black Friday and Cyber Monday in a few minutes. Tell flayr the goal, the dates and the offer; it plans the posts and writes every draft. Each post waits for your approval before it is scheduled. ## How to use it 1. Choose **Build a campaign**. It is on Home, in Studio and Create, on the Calendar, on the Campaigns page, in Chat, in the Library, on your brand page and in Connections. 2. Pick a goal: **Sale**, **Launch** or **Holiday**. Holiday has a one-tap button that fills in the Black Friday to Cyber Monday dates. 3. Name the campaign, set **Starts** and **Ends**, describe the offer in a few words and choose the platforms. A discount and a code are optional. 4. Choose **Next** and pick the products to feature. Each one gets its own spotlight post. You can skip this step. 5. On **Review & generate**, check the planned posts and the estimated cost in Embers, then choose **Generate drafts**. 6. Read the drafts on the campaign page and edit any caption. 7. Choose **Book posts** to add them to your calendar at their planned times. ## Good to know - Nothing posts on its own. Each booked post waits for your review before it is scheduled. - A sale plan runs from a teaser and a countdown through launch day, product spotlights, a reminder and a last chance, to a thank-you post. - Writing the drafts uses Embers. You see the estimate before you generate. - Products come from your connected store, or you can add one by hand. - Building and reviewing campaigns is free on every plan. Booking the posts to your connected accounts needs a plan with scheduling (Standard or higher). ## Overview Plan a sale, a launch or a holiday push such as Black Friday and Cyber Monday in a few minutes. Tell flayr the goal, the dates and the offer; it plans the posts and writes every draft. Each post waits for your approval before it is scheduled. null 1. Choose Build a campaign. It is on Home, in Studio and Create, on the Calendar, on the Campaigns page, in Chat, in the Library, on your brand page and in Connections. 2. Pick a goal: Sale, Launch or Holiday. Holiday has a one-tap button that fills in the Black Friday to Cyber Monday dates. 3. Name the campaign, set Starts and Ends, describe the offer in a few words and choose the platforms. A discount and a code are optional. 4. Choose Next and pick the products to feature. Each one gets its own spotlight post. You can skip this step. 5. On Review & generate, check the planned posts and the estimated cost in Embers, then choose Generate drafts. 6. Read the drafts on the campaign page and edit any caption. 7. Choose Book posts to add them to your calendar at their planned times. ## How a local tech shop planned its whole Cyber Week in one sitting (Shopify + flayr) ## A local shop's whole Cyber Week, built in flayr ## Shopify store to social posts in a minute ## A Black Friday post from a real Shopify product ## 19 holiday posts, one approval --- Source: https://flayr.social/help/features/character-studio # Character Studio Create your brand's own character: a look, a voice and a personality you can post as. A guided setup builds it step by step, then you make stills, clips and narrated clips of it. Everything it makes lands in your Library as a draft; nothing posts on its own. ## How to use it 1. Open **Studio** and pick the **Characters** card, then **Create your first character**. 2. Choose the brand it belongs to, and an Area if you use them. Characters belong to one brand. 3. Work through the setup: **Concept**, **Look**, **Voice**, **Personality**, **Motion**, **Test scenes** and **Activate**. The side panel shows an Embers estimate as you go. 4. On the character page, use **Make a still**, **Make a clip** or **Make a narrated clip**. 5. Find the result in your Library as a draft, labelled with the character. ## Good to know - To change an active character, use the **Versions** tab: change something, compare, then approve or discard. You can restore an older version. - Viewers can look at a character but only editors and above can create or make with one. - Characters start on Standard. The Free plan does not include characters. - The test scenes make a still, a clip and a narrated clip. ## Create a character Start your brand's own character. It belongs to one brand, and only editors and above can create one. null 1. Open Characters Open **Characters** from the sidebar, or the **Characters** card in Studio. 2. Start a new character Choose **New character** (or **Create your first character**). 3. Name it and pick its brand Give it a name, say what kind of character it is if you like, pick the brand and choose **Start setup**. ## Guided setup Seven steps build the character: Concept, Look, Voice, Personality, Motion, Test scenes and Activate. Look, Voice, Personality and Motion open once Concept is done. null 1. Concept Write a one-line concept and who it is for. An originality check runs here; if it flags the character, add a note on why it is original or yours. 2. Look Upload your own art or pick a ready-made style, add style notes, colours and rules, then choose the hero image. 3. Voice Pick a stock voice, your cloned voice, or design a new one, and audition it. 4. Personality Set its traits and humour, the things it says and never says, and try it with **Ask it something**. 5. Motion Pick a motion style and a default camera. 6. Test scenes Choose **Run tests**, then rate each scene. Scenes need a rating of 3 or more to activate. 7. Activate Check the list and choose **Activate**. A draft character shows **Continue setup** until then. ## Make with your character Make stills, clips and narrated clips of an active character. Everything lands in your Library as a draft; nothing posts on its own. null 1. Open the character Open **Characters** and pick the character. 2. Choose what to make Choose **Make a still**, **Make a clip** or **Make a narrated clip**. 3. Find it in your Library The result is a draft in your Library, labelled with the character. ## Versions Change an active character safely: propose a change, compare it, then approve or discard it. Older versions can be restored. null 1. Open the Versions tab On the character page, open **Versions**. 2. Propose a change Change something and choose **Propose the change**. 3. Approve or discard it Compare it with the current version, then choose **Approve** or **Discard**. 4. Restore an older version In the history, choose **Restore** on the version you want back. ## Character Studio in flayr: build a character in rounds, then talk to it ## Make your own brand character in flayr Character Studio ## Build a character in rounds, then talk to it, in two minutes --- Source: https://flayr.social/help/features/campaigns # Campaigns Plan a coordinated launch in one place: a goal, a timeline, the organic posts and the paid ads. A drip plan spreads your content across the campaign, from teasers to follow-ups. ## How to use it 1. Open **Campaigns** and create a campaign. 2. Set its goal and channels, and the date range in **Budget and schedule**. 3. Attach content. In the **Drip plan**, give each piece a role and pick a posting time; flayr spreads them across the campaign. 4. If your plan includes ads, set a paid budget and attach ad campaigns. 5. Finish the readiness checklist, then **Schedule campaign**. Its posts go out from your connected accounts at their planned times. ## Good to know - Pausing a campaign holds any posts that have not gone out yet. - The paid budget is locked once the campaign leaves draft. ## Overview Plan a coordinated launch in one place: a goal, a timeline, the organic posts and the paid ads. A drip plan spreads your content across the campaign, from teasers to follow-ups. null 1. Open Campaigns and create a campaign. 2. Set its goal and channels, and the date range in Budget and schedule. 3. Attach content. In the **Drip plan**, give each piece a role and pick a posting time; flayr spreads them across the campaign. 4. If your plan includes ads, set a paid budget and attach ad campaigns. 5. Finish the readiness checklist, then Schedule campaign. Its posts go out from your connected accounts at their planned times. --- Source: https://flayr.social/help/features/find-connections # Where to find Connections Where connections, API keys and Developers live in flayr, what each one is for and which plans can use them. Start here, then connect an MCP client, your AI agent or the API. Start here. Then follow the tutorial for your tool: Connect over MCP, Connect your AI agent or Use the API. ## Connections: your social accounts Connections is where you link the social accounts flayr posts to. null 1. Open Connections Choose Connections in the sidebar. Each platform has a card with a Connect Account button. 2. Know what it is for Connections links social accounts, so flayr can publish and schedule to them. API keys, MCP and AI agents are not set up here: they are in Developers. ## Developers: API keys, webhooks and MCP Developers is where you create API keys, watch usage, manage webhooks and find the MCP server for AI agents. null 1. Open Developers Choose Developers in the sidebar. On a plan without API access, the page shows which plan you need. 2. API Keys Create and revoke the keys that an agent, an MCP client or a script signs in with. flayr shows a new key once. 3. Usage Your API requests this month, against your monthly quota. 4. Webhooks Add a URL that flayr calls when an event happens in your account. 5. MCP server (AI agents) The server an AI agent or MCP client connects to. ## Settings: connected agents Settings, then Integrations lists the agents that signed in to flayr, and has the same API keys as Developers. null 1. Open Settings, then Integrations Scroll down to Advanced and open it. 2. Connected Agents Agents that connected by signing in to flayr, such as a Claude connector, are listed here. 3. Developer API The same API keys as on the Developers page. ## Which plans can use them What your plan needs before you start. null 1. Social accounts Connecting a social account needs a paid plan. How many accounts you can connect depends on the plan. 2. API keys, MCP and agents API keys, MCP and AI agents need a plan with API access. The Developers page shows which plan you need. 3. On a free trial A trial counts. While it runs, your key works like a key on the plan you are trying. Create the key in Personal, where keys are account-wide: the trial does not carry into a key bound to one brand. When the trial ends, you need the paid plan to keep the connection working. 4. Pick your tutorial MCP for Claude, Cursor and other MCP clients. The AI agent tutorial for the key and the approval settings. The API for scripts and automation tools. --- Source: https://flayr.social/help/features/connect-mcp # Connect over MCP Connect Claude Code, Claude Desktop, Claude.ai, Cursor or any MCP client to flayr with one URL, so your AI agent can draft and schedule posts. It uses an API key or a flayr sign-in. One URL for every MCP client. Pick your client below, then check that it works. ## The MCP server URL Every MCP client connects to the same URL. null 1. Copy the MCP server URL Every client in this tutorial connects to this URL. 2. Have an API key ready A client that connects with a key sends it in the Authorization header. Wherever you see flayr_sk_YOUR_KEY, put your own key. No key yet? Create one in Connect your AI agent. ## Claude Code One command in your terminal. null 1. Run the command Paste it into a terminal, with your key in place of flayr_sk_YOUR_KEY. 2. Check flayr is listed In Claude Code, run /mcp. flayr appears in the list of servers. ## Claude Desktop and Claude.ai A custom connector. No API key or config file: you sign in to flayr instead, and pick the brand. null 1. Add a custom connector In Claude Desktop or claude.ai, open Settings, then Connectors, and choose Add custom connector. 2. Name it flayr and paste the URL Leave the advanced OAuth fields empty. 3. Connect and sign in Choose Connect, sign in to flayr, pick your brand and allow what it may do. ## Cursor and any other MCP client Any client that supports remote (Streamable HTTP) MCP servers with headers takes the same block. null 1. Add the server in Cursor Open Settings, then MCP, then Add new MCP server, or edit ~/.cursor/mcp.json. Paste the block with your key in place of flayr_sk_YOUR_KEY. 2. Another MCP client Give it the server URL and the Authorization header from the first section. ## Check it works Two quick checks: the URL answers, and your agent knows your brand. null 1. Check the URL answers Run this in a terminal. The server answers it without a key, so it shows the URL is right. 2. Ask your agent Ask the question below. A working connection calls the whoami tool and answers with your brand (or "all your brands" for an account-wide key) and your plan. --- Source: https://flayr.social/help/features/connect-ai-agent # Connect your AI agent Give Claude, ChatGPT, Cursor or another AI agent its own flayr API key, so it can draft, schedule and report on your posts over MCP. Connect it with Read + Write and keep Post review on, so nothing posts without your approval. Create a key for the agent, keep approval on, connect it and check that it works. About five minutes. ## Create the key One key per agent, with the recommended scope: Read + Write, no Publish. null 1. Open Developers, then API Keys Choose Developers in the sidebar and find API Keys. 2. Name the key after the agent For example "Claude Code". With one key per agent, you can revoke one without breaking the others. 3. Pick Read + Write, leave Publish off This is the recommended scope, and the default. The agent drafts posts, media and campaigns. Nothing goes live until you schedule or publish it in flayr. 4. Create the key and copy it Choose Create key and use the copy button. flayr shows the full key once. Store it like a password. 5. Check the key Run this in a terminal, with your new key in place of flayr_sk_YOUR_KEY. ## Nothing posts without your approval Two settings keep you in control of what goes live. null 1. Keep Publish off the key A key without the Publish scope can never post. The agent can only prepare drafts. 2. Set Post review to Required Open Brand Intelligence, then Post review, and choose Required. Scheduled posts then wait for your review, including posts scheduled by an agent whose key has the Publish scope. ## What the agent can do The agent works through tools. The scopes on its key decide which ones it may use. null 1. Read Read tools only look. 2. Write Write tools change drafts in flayr. 3. Publish Publish tools act on your real accounts and need a key with the Publish scope. A key without it can never post. 4. See every tool The full list, grouped by Read, Write and Publish, is in the agent reference. ## Connect the agent Give the agent the MCP server URL and its key. null 1. Claude Code Run this in a terminal with your key in place of flayr_sk_YOUR_KEY, then run /mcp to see flayr listed. 2. Any other agent Claude Desktop, Claude.ai, Cursor and other MCP clients are in Connect over MCP. Scripts and automation tools are in Use the API. ## Check it works One question tells you the agent is connected to the right brand. null 1. Ask your agent Ask the question below. A working setup calls the whoami tool and answers with your brand (or "all your brands" for an account-wide key) and your plan. --- Source: https://flayr.social/help/features/use-the-api # Use the API Call the flayr v2 API with an API key: one curl example, and the generic HTTP step for automation tools such as n8n, Zapier and Make. For scripts and tools that connect without MCP or an AI agent. Check your key, create a draft with one request, then do the same from an automation tool. ## Check your key Every request sends your API key in the Authorization header. null 1. Create an API key Open Developers, then API Keys. The steps are in Connect your AI agent. Read + Write is enough for this tutorial. 2. Call ping Run this in a terminal, with your key in place of flayr_sk_YOUR_KEY. ## Create a draft with curl One request creates a draft in flayr. Nothing is posted. null 1. Send the request It creates a draft with the text you send. 2. Check the answer A working request answers HTTP 201 with the id of the draft. The draft is saved in flayr. Nothing was posted. ## n8n, Zapier, Make and other automation tools Automation tools call the same API through their generic HTTP or webhook step. null 1. Add the HTTP step In n8n it is the HTTP Request node. In Zapier it is Webhooks by Zapier. In Make it is HTTP, Make a request. Any tool with a generic HTTP step works the same way. 2. Add your key as a header Use the name and the value below, with your key in place of flayr_sk_YOUR_KEY. 3. Check it with a GET Set the method to GET, paste the URL and run the step. A working key answers "authenticated": true. 4. Create a draft with a POST Set the method to POST and the body type to JSON, then paste the URL and the body. Run the step. The answer shows "status": "draft". Nothing is posted. 5. Field names for your tool The exact field names for n8n, Zapier and Make are in the agent reference. ## Reference and webhooks Where to look up every endpoint, and how flayr can call your tool. null 1. Open the API reference Every endpoint of the v2 API is in the public reference. 2. Let flayr call your tool To hear about events as they happen, add a webhook in Developers, under Webhooks. --- Source: https://flayr.social/help/how-to/flayr-01-overview # flayr in two minutes: chat, studio, calendar, queues, workflows A light tour of flayr: generate posts, carousels and videos through chat (it tells you what each model costs), plan-only or full-approve modes, the studio, what's pending, the calendar and queues that post automatically, workflows, ads, your library and brand intelligence, and analytics. --- Source: https://flayr.social/help/how-to/flayr-02-opus-clip-integration # Pull your Opus Clip clips straight into flayr Connect Opus Clip in Settings → Integrations with your Opus API key, then send a video to Opus from your library, or link an existing Opus project by its ID and import the clips. They land in your library, ready to schedule. --- Source: https://flayr.social/help/how-to/flayr-03-print-shop-daily-queue # I drag in a print, flayr posts one every day A pile of 3D prints and one on YouTube Shorts every day: a daily queue in flayr. Drag new content in and it keeps posting a print a day. The more you add to the library, the longer it runs. --- Source: https://flayr.social/help/how-to/flayr-04-workflows-light # Automating cross-posting with flayr workflows (quick walkthrough) Start from a template (like cross-platform sync) or build your own. Every node has a trigger, config, and inputs and outputs; variables pass from one step to the next. An AI text step writes the caption before posting. --- Source: https://flayr.social/help/how-to/flayr-05-scheduling # Scheduling in flayr: drag, drop, and let the queue run Drafts on the left, calendar on the right. Drag one in and pick a time. See every profile at once or one brand at a time, turn suggested times on or off, and let a queue auto-schedule a print a day. --- Source: https://flayr.social/help/how-to/flayr-06-voice-cloning # Clone your voice in flayr's Voice Studio Open Voice Studio and start a voice cloning session. It walks you through short cards to read out loud, then builds your voice from the clean seconds of your recording. Pick your clone, type a line and generate audio: a first run, then the updated version with delivery and sounds. --- Source: https://flayr.social/help/how-to/flayr-07-ad-accounts-setup # Ads 1: set up your ad accounts Connect the social accounts your ads run from, then link the ad account for each platform so flayr can build and track campaigns for this company. --- Source: https://flayr.social/help/how-to/flayr-08-paused-campaign-build # Ads 2: build a campaign that starts paused Build the whole campaign in flayr, audience, budget and creative, and leave it paused, so nothing spends until you have checked it and turned it on. --- Source: https://flayr.social/help/how-to/flayr-09-comment-to-get # Ads 3: comment-to-get, reply automatically to a keyword Ask people to comment a keyword on your post or ad. An auto-reply trigger answers each comment and sends the DM with what you promised. --- Source: https://flayr.social/help/how-to/flayr-10-hook-testing # Ads 4: test your hooks Post the same idea with different opening hooks and compare how each one does in analytics before you put ad money behind the winner. --- Source: https://flayr.social/help/how-to/flayr-11-the-funnel # Ads 5: the funnel, from ad to comment to customer Follow people from the ad to the comment, the DM and the sale with a funnel in advanced insights, and see where they drop off. --- Source: https://flayr.social/help/how-to/flayr-12-ab-testing # Ads 6: A/B test your ads Run two versions of an ad side by side, compare the results in Ads, and keep the one that works. --- Source: https://flayr.social/help/how-to/flayr-13-real-results # Ads 7: real results What the series produced on a real account: spend, comments, DMs and results, read from flayr analytics. --- Source: https://flayr.social/help/how-to/flayr-14-templates-walkthrough # Templates: start from Record Room, Poem, a segment ad or a weekly campaign A walk through the templates gallery: what each template takes in and makes, how "Use this template" starts it with your brand kit, and where to see example campaigns built with it. --- Source: https://flayr.social/help/how-to/flayr-15-post-everywhere # Post to every platform at once, then see what's working Connect your accounts, write one post, send it to all of them now or on a schedule, then read which post and which platform is ahead. 1. Open Connections Open **Connections** from the sidebar. Each platform has a card. [Open Connections](/connect) 2. Connect an account Choose **Connect Account** on a platform card. Sign in on the platform's own page and allow what it asks for. The card then says **Connected**. [Open Connections](/connect) 3. Facebook: pick your Page After Facebook sign-in, **Select Facebook Page** lists your Pages. Pick one and choose **Connect Facebook Page**. 4. Connect the rest Repeat for each account. The posting trial covers up to 3 connected accounts. The bar at the top of Connections shows how many you have used. [Open Connections](/connect) 5. Open Post Studio Open **Studio** and choose **Post studio**. [Open Studio](/studio) 6. Check Post to The **Post to** row already has your connected accounts picked. Tap one to leave it out. [Open Post studio](/create/post) 7. Write the caption Write it once. The counter shows the shortest limit of the platforms you picked. 8. Add a photo or video Add your photo or video. Instagram, TikTok, YouTube, Pinterest and Snapchat need one. If it is missing, choose **Attach from library**, **Generate an image**, or **Post without** those platforms. 9. Publish now Choose **Publish now**. Check the list of places in "Publish now?" and confirm. 10. Or schedule it Choose **Schedule**, pick a date and time, then **Schedule**, and confirm. 11. Check it went out Open **Schedule**, then **Upcoming**, then **Published**. Every publish is listed, newest first. [Open the publish log](/schedule?tab=upcoming&mode=log) 12. See what's working Open **Insights**. Reach, Engagements and Engagement Rate are at the top, **Platform Comparison** below. First numbers arrive within about a day. **What's working / what isn't** fills in after about five posts of a kind. [Open Insights](/insights) [Start in Connections](/connect) --- Source: https://flayr.social/help/how-to/flayr-16-many-accounts # Run many accounts from one place Add each brand as a workspace, connect its accounts, post for one brand or plan them all on one calendar, then check each brand in Insights. 1. Open Workspaces Switch the sidebar to **Advanced**, then open **Workspaces**. On Agency plans the page is called **Clients**. One brand only? Skip to step 3. [Open Workspaces](/clients) 2. Add a workspace Choose **Add workspace** (or **Add Client**), type the brand's name and choose **Create**. More than one brand needs a Business plan or higher. [Open Workspaces](/clients) 3. Open Connections for that brand Open **Connections**. The header says "Connecting accounts for" and the brand. Choose **Switch workspace** if it is the wrong one. [Open Connections](/connect) 4. Connect its accounts Choose **Connect Account** on each platform card and sign in on the platform's own page. For a second account on the same platform, choose **Connect another ... account or Page** under the card. [Open Connections](/connect) 5. Set the default accounts Under **This workspace's accounts**, pick one account per platform. "Choose when posting" means flayr asks each time. [Open Connections](/connect) 6. Switch to the brand Pick the brand in the brand switcher. Everything you make now belongs to that brand. 7. Write and post Open **Studio**, then **Post studio**. **Post to** shows this brand's accounts. Write the caption, add a photo or video, then **Publish now** or **Schedule**, and confirm. [Open Post studio](/create/post) 8. See every brand on one calendar Open **Schedule**. Use **Posts from** to pick **All profiles** or one brand. Drag a draft onto a day to book it. **Upcoming** lists what is booked. **Published** lists what went out. [Open Schedule](/schedule) 9. Check what's working Open **Insights**. It shows the brand you are on. **What's working / what isn't** fills in after about five posts of a kind. First numbers arrive within about a day. [Open Insights](/insights) [Start in Workspaces](/clients) --- Source: https://flayr.social/help/how-to/flayr-17-campaign-builder # Build a campaign: a sale or launch, planned and drafted for you From "Build a campaign" to a booked calendar: pick a goal, set the dates and the offer, choose your products, review the planned posts and approve the drafts. Shown with a Black Friday to Cyber Monday sale. 1. Open the campaign builder Choose **Build a campaign**. The link below goes straight to it. [Open the campaign builder](/create/campaign) 2. Goal, dates and offer In **Goal, dates & offer**, pick what the campaign is for, the first and last day, and the deal you are running. 3. Pick the products In **Products**, choose the products the posts should show. 4. Check and make the drafts In **Review & generate**, look over the plan and what it costs, then press **Generate drafts**. 5. Approve before anything goes out Read the drafts, then press **Book posts** to put them on your calendar. Each one waits for your OK in **Pending**. Nothing posts until you approve it. [Open Pending](/publish) Your posts are waiting for you. Next, read them and approve the ones you like. [Open the campaign builder](/create/campaign) --- Source: https://flayr.social/help/how-to/start-connect-store # Connect your store Link your Shopify store so flayr can see your products. It only reads them. Nothing in your store changes. 1. Open Connections Open **Connections** from the sidebar, then the **Content Sources** tab. The Shopify card is there. [Open Content Sources](/connect?tab=content-sources) 2. Start from the Shopify card Follow the button on the Shopify card. It takes you to Shopify, where you add the flayr app to your store. 3. Say yes in Shopify Shopify shows what the app can see. flayr reads your products and nothing else. Approve it, and Shopify sends you back to flayr. 4. Check the card Back in **Content Sources**, the card shows your store name. That is all: your store is linked. [Open Content Sources](/connect?tab=content-sources) Your store is linked. Next, bring in the products you want to post about. [Open your store connection](/connect?tab=content-sources) --- Source: https://flayr.social/help/how-to/start-products # Bring in your products Pick the products you want to post about. flayr copies their names, photos and prices so a post can use them. 1. Open Import from Shopify Open **Connections**, then **Content Sources**. Under your store is **Import from Shopify**. [Open Content Sources](/connect?tab=content-sources) 2. Choose what to import Press **Choose what to import**. Tick the products or collections you want. Nothing is ticked for you. 3. Confirm Press **Confirm**. The import takes about a minute. You can leave the page while it runs. 4. Refresh later Changed a price or a photo in Shopify? Press **Import now** to bring in the latest. [Open Content Sources](/connect?tab=content-sources) Your products are in. Next, set up your brand so posts sound like you. [Choose products](/connect?tab=content-sources) --- Source: https://flayr.social/help/how-to/start-brand-setup # Set up your brand Tell flayr how your shop looks and sounds, once. Every post it writes after that starts from your brand. 1. Open Brand Intelligence Open **Brand Intelligence** from the sidebar. [Open Brand Intelligence](/brand) 2. Start from your website On a paid plan, type your website address and press **Fetch Brand**. flayr reads the site and fills in what it finds about how you look and sound. 3. Check how you sound Read what flayr found and fix anything that is off. No website? Press **Add Brand Voice** and describe how you write in your own words. 4. Add your logo Press **Upload Asset** to add your logo or a photo you use often. Your brand is set. Next, connect the social accounts you post to. [Open Brand Intelligence](/brand) --- Source: https://flayr.social/help/how-to/start-connect-accounts # Connect your social accounts Link Instagram, Facebook, TikTok and the rest, so one post can go to all of them. 1. Open Connections Open **Connections** from the sidebar. Each platform has its own card. [Open Connections](/connect) 2. Connect one account Press **Connect Account** on a card. Sign in on the platform's own page and allow what it asks for. Back in flayr, the card says it is connected. [Open Connections](/connect) 3. Facebook: pick your Page After you sign in to Facebook, **Select Facebook Page** lists your Pages. Pick one and press **Connect Facebook Page**. 4. Connect the rest Do the same for each account you post to. [Open Connections](/connect) Your accounts are connected. Next, write your first post and send it. [Open Connections](/connect) --- Source: https://flayr.social/help/how-to/start-first-post # Write one post and send it Write a post once and send it to every account you picked, right now. 1. Start a post Open **Studio** from the sidebar and start a post. The link below opens it directly. [Write a post](/create/post) 2. Check Post to The **Post to** row already has your connected accounts picked. Tap one to leave it out. 3. Write it once Type what you want to say. The counter shows how much room the shortest platform gives you. 4. Add a photo or video Press **Add photo or video** and pick one from your phone or computer. Instagram, TikTok, YouTube and Pinterest need one. 5. Publish now Press **Publish now**. Check the list of places in "Publish now?" and confirm. Your first post is out. Next, add your own photos and videos so they are ready for the next one. [Write a post](/create/post) --- Source: https://flayr.social/help/how-to/start-own-media # Add your own photo or video Put your product photos and videos in one place, so they are ready whenever you write a post. 1. Open Library Open **Library** from the sidebar. [Open Library](/library) 2. Add your files Drag photos or videos onto the page, or press **Choose files** and pick them. On a phone you can pick from your camera roll. 3. Give it a name After the upload, flayr asks you to name it. Type a title you will remember and press **Save details**. 4. Use it in a post When you write a post, press **Attach from library** to pick from what you saved. [Write a post](/create/post) Your photos and videos are saved. Next, pick a day and time for a post instead of sending it right away. [Open Library](/library) --- Source: https://flayr.social/help/how-to/start-schedule # Schedule a post and see your calendar Pick a day and time for a post. flayr sends it for you, and the calendar shows everything that is planned. 1. Write the post Write a post the same way as before, but do not publish it yet. [Write a post](/create/post) 2. Pick a time Press **Schedule**. Pick a quick time like **Tomorrow 9 am**, or choose your own day and time. 3. Confirm Check the time and the list of places in "Schedule this post?" and confirm. 4. See it on the calendar Open **Schedule** from the sidebar. Your post sits on its day. You can also drag a draft onto a day to book it. [Open Schedule](/schedule) 5. Check it went out After the time has passed, open **Upcoming**, then **Log**. Every post that went out is listed, newest first. [Open the log](/schedule?tab=upcoming&mode=log) Your post is on the calendar. Next, plan a whole sale at once with a campaign. [Open Schedule](/schedule) --- Source: https://flayr.social/help/how-to/start-approvals # Approve posts before they go out Read every post that is waiting for you in one place. Say yes, fix it, or hold it. Nothing goes out without your OK. 1. Open Pending Open **Pending** from the sidebar, then **Needs review**. Every post waiting for you is listed. [Open Pending](/publish) 2. Read a post Each post shows the words, the picture, and where and when it will go out. 3. Say yes Happy with it? Press **Looks good**. The post goes out at its time. 4. Fix it or hold it Want to change the words or the picture? Press **Edit**. Not sure yet? Press **Hold** and it stays put until you decide. 5. Finish the list When the page says **Nothing waiting on you**, you are done. [Open Pending](/publish) Your posts are approved and booked. Next, make a picture for a post when you do not have a photo. [Open Pending](/publish) --- Source: https://flayr.social/help/how-to/start-ai-images # Make a picture for a post No photo for a post? Describe the picture you want and flayr makes it. 1. Start a post Start a post and write what you want to say first. The picture is made to match your words. [Write a post](/create/post) 2. Ask for a picture Press **Generate an image**. A box opens with a description already started from your words. 3. Describe it Say what should be in the picture, in plain words: the product, the place, the mood. Then press **Generate Image**. Making a picture uses Embers, your credits. 4. Add it to the post Like it? Press **Add to Post**. Not right? Change the description and make another. Your post has a picture. Next, make a short video the same way. [Write a post](/create/post) --- Source: https://flayr.social/help/how-to/start-ai-video # Make a short video Describe a short video and flayr makes it. Use it in a post or save it to your phone or computer. 1. Open Video Open **Video** from the sidebar. [Open Video](/compose) 2. Describe your video In **Describe your video**, say what should happen: what is shown, where, and how it moves. Pick how many seconds it runs. 3. Make it Press **Generate Video**. It takes a few minutes, and a longer video uses more Embers, your credits. 4. Watch it and use it The finished video is under **Your Videos**. Watch it, then use it in a post or press **Download video** to save it. [Open Video](/compose) Your video is made. Next, add a spoken voice to it. [Open Video](/compose) --- Source: https://flayr.social/help/how-to/start-voice # Make a voiceover Type what you want said and pick a voice. flayr reads it out loud, ready to put on a video. 1. Open Voice Open **Voice** from the sidebar and find **Generate Speech**. [Open Voice](/voice) 2. Type the words Type what you want said, the way you would say it out loud. Short sentences sound best. 3. Pick a voice Pick one of the ready-made voices from the list. 4. Make it and listen Press **Generate Audio**, then play it back. Change the words or the voice and try again until it sounds right. 5. Put it on a video Press **Use in Video Composer** to add the voice to a video. Your voiceover is ready. Next, put a little money behind a post that is doing well. [Open Voice](/voice) --- Source: https://flayr.social/help/how-to/start-ads-boost # Boost a post Put a small budget behind a post that is already out, so more people see it. You set the most it can spend. 1. Set up ads once Switch the sidebar to **Advanced** and open **Ads**. The first time, follow the setup to link your Meta ad account. Ads need a plan that includes them. [Open Ads](/ads) 2. Pick a post that is out Open a post you already published to Facebook or Instagram and press **Boost this post**. 3. Set the budget and the days Choose how much to spend a day and for how many days. The review shows the most it can spend in total. 4. Create it paused Press **Create paused boost**. Nothing is spending yet. 5. Switch it on Ready? Press **Start boost** and confirm in "Switch this ad on?". Meta bills your ad account directly. flayr adds no fee. 6. Watch how it does Open **Ads** and look under **Boosted posts** to see how each boost is doing. [Open Ads](/ads) Your boost is running. Next, answer the comments it brings in. [Open Ads](/ads) --- Source: https://flayr.social/help/how-to/start-inbox # Answer comments in one place See the comments people leave on your posts and answer them without opening each app. 1. Open Inbox Switch the sidebar to **Advanced** and open **Inbox**. The inbox needs a plan that includes it. [Open Inbox](/inbox) 2. See what needs an answer **Needs reply** lists the comments nobody has answered yet. 3. Write a reply Type your answer under the comment. Stuck? **Suggest reply** writes a first try for you to edit. It uses a few Embers, your credits. 4. Send it Press **Send reply**. The answer shows up on the platform, and the comment leaves the list. Your comments are answered. Next, look at your numbers to see which posts work. [Open Inbox](/inbox) --- Source: https://flayr.social/help/how-to/start-analytics # Read your numbers See which posts and which platforms do best, so you know what to make more of. 1. Open Insights Open **Insights** from the sidebar. The numbers need a paid plan and at least one post that went out. [Open Insights](/insights) 2. Pick the days Choose the time you want to look at, for example **Last 7 days**. 3. Read the top row The top row shows how many people saw your posts and how many did something with them. **Engagement Rate** is the share of people who liked, commented or shared. 4. Compare your platforms **Platform Comparison** shows which platform is ahead. **Best Posting Times** shows the days and hours your posts did best. 5. Give it a day New posts take about a day to show numbers, because the platforms report them late. [Open Insights](/insights) You know what works. Next, make more posts like your best one, or plan your next sale with a campaign. [Open Insights](/insights) --- Source: https://flayr.social/help/how-to/flayr-32-commerce-tutorial # From your store to your Black Friday and Cyber Monday campaign Connect your store or add products by hand, build your campaign, review it together, and put it on the calendar. Your drafts wait for your approval. 1. Connect your store — or continue without one Open **Content Sources** in Connections. Check the workspace name, then connect Shopify or your own compatible store with its Store API address and key. No supported store? Continue to **Build a campaign** and add products by hand. You do not need a store connection to finish. [Open store connections](/connect?tab=content-sources) 2. Check your products came in Import your products in Content Sources and check their names, photos and prices. Without a store, add those details in the campaign’s **Products** step, including the product page URL if you have one. Check the details before using them. [Check imported products](/connect?tab=content-sources) 3. Build a campaign and choose the holiday Choose **Holiday**, then **Use Black Friday – Cyber Monday**, or **Use Cyber Week with a lead-up** for posts before and after the sale. Check the dates and time zone shown in the builder: these come from the campaign presets each year. [Build a campaign](/create/campaign) 4. Pick products and the offer Name the campaign, enter the real offer and choose where to post. Choose **Next** to pick products from your store or add them by hand. Then review the plan and Embers estimate and choose **Generate**. This creates a real campaign in this workspace; nothing publishes here. [Choose products and offer](/create/campaign) 5. Review the plan week by week Wait for the drafts to finish. Read the captions, product details and offer. Check the weeks in the campaign plan, then choose **Book posts**. Open **Needs review** to approve the booked set. Posts from this tutorial wait for approval. Do not approve a partial set if generation stopped. [Open your campaign plan](/campaigns) 6. Approve the set when you are happy In **Needs review**, find your campaign or its queue by name. Review the set and choose **Approve**, then confirm. Hold anything that needs changes. If the queue has not reached the approval window yet, leave it pending and return when it appears. You can leave now with a real pending campaign and come back to approve it later. [Open Needs review](/publish?tab=review) 7. See it on the calendar Open Schedule and check the dates and destination accounts. If nothing is booked yet, return to your campaign and choose **Book posts**. Posts that still need approval wait for review before they can publish. [Open the calendar](/schedule) 8. Optional: boost the best post (Advanced) After posts have results, check Insights for the strongest one. In **Advanced**, open Ads to prepare a boost and review the audience and budget. Boosting is optional and has its own approval; finishing this tutorial never starts ad spend. [Open Ads (Advanced)](/ads) [Start with your store](/connect?tab=content-sources) --- Source: https://flayr.social/help/how-to/flayr-33-weekly-progress-report # Automate a weekly progress report in flayr Freeze your week’s numbers, turn them into a short script and video, approve it, post it, and follow up the next day. We built this for Ember, our mascot, who posts its own weekly numbers. 1. Install the template Open **Workflow templates** and choose **Use this template** on **Weekly progress report**. It is the same chain Ember uses each week: numbers, script, video, approval, posts, next-day follow-up. The template needs the Starter plan or higher, because it uses an approval step. [Open workflow templates](/workflows/templates) 2. Freeze the week’s numbers The **Weekly report** step runs once a week (Friday 09:00 UTC by default; change the day, time and time zone in its settings). **Freeze this week’s numbers** then freezes your followers and reach for the week. Pin a brand with connected accounts first. A count a platform did not report says **not reported**, never 0. Ember’s report freezes its numbers the same way, so a slow week reads as a slow week. [Open your workflows](/workflows) 3. Turn the numbers into a script The **Write the script** step writes a short spoken script (45 seconds by default) from the frozen numbers only: a hook, the numbers, one honest line about what changed, and a question for next week. Edit the prompt to match your voice. Ember’s script opens with a hook and states every number exactly as frozen. [Edit the script step](/workflows) 4. Make the video The **Make the video** step turns the script into a short vertical video (8 seconds, 9:16 by default). Change the length or shape in its settings. Video generation spends Embers; check the estimate on the step before you switch the workflow on. [Edit the video step](/workflows) 5. Approve before anything posts The **Approve the weekly report** step parks the run until someone approves it. The script and video wait in **Needs review**. Nothing publishes until you approve. Ember’s report also waits for approval every week. [Open Needs review](/publish?tab=review) 6. Pick where it posts Each **Post to** step needs an account: open it and choose the connected TikTok, Instagram, YouTube or LinkedIn account. Delete the platforms you do not use. Until each step has an account, the workflow shows what is missing and will not run. [Choose your accounts](/workflows) 7. Follow up the next day One day after you approve, **Write the follow-up** drafts a short LinkedIn post that repeats one number from the report and thanks viewers. It does not claim how the video performed. It waits in **Needs review** at **Approve the follow-up**. Ember’s follow-up goes further and compares its video versions; read your post results in Analytics before your next report. [Open Analytics](/analytics) Switch the workflow on and approve your first report on Friday. Each week, read last week’s results in Analytics and adjust the script prompt. [Use the weekly progress report template](/workflows/templates) --- Source: https://flayr.social/help/testimonials # Testimonials Ember is the Dostal logo as a living dragon, and there's a semi-chibi AI me next to him. Character Studio keeps each one on-model from its own character bible: 42 scenes so far across three characters. Mathew Dostal · co-founder, flayr · Dostal Tech I read into Voice Studio for about 39 minutes and it trained a clone of my own voice, on hardware we host ourselves. It's my voice, not a voiceover. Mathew Dostal · co-founder, flayr · Dostal Tech flayr turns each poem into a carousel with my words on matched stock photos, and a stock-footage video with the poem over it, then parks both for my approval. Nothing goes out until I say so. So far I haven't. Mathew Dostal · co-founder, flayr · Life Dostal When I publish a poem on my own site, it lands in flayr as a draft. Sanity stays the source of truth; flayr just gets a copy to work with. Mathew Dostal · co-founder, flayr · life.mdostal.com My print channel has put out a timelapse every evening at 7 since September 28. Twenty days, six platforms, 120 of 120 posts out, and the queue posted every one. Mathew Dostal · co-founder, flayr · Dostal Prints I had Opus Clip and Claude cut my Pantheon videos into shorts, and flayr's queues put one out at 9 every weekday on eight platforms. Fourteen Pantheon posts so far, 102 platform posts, none of the multi-platform ones failed. Mathew Dostal · co-founder, flayr · Dostal Tech --- Source: https://flayr.social/help/submit # Submit a tutorial video Sign in to submit a tutorial video or testimonial. Choose a feature and section, then send your video for review. Approved videos appear on the matching help page. Your private submissions are only available in the signed-in page. [Submit a video](/help/submit) --- Source: https://flayr.social/help/templates # Templates ## Record Room Numbered "STEP 0N" tips as 9:16 Shorts and 1:1 or 4:5 carousel cards, in your brand colors. What you bring: A topic and three to seven short tips, in your words. What you get: One Short per step plus a carousel, saved as drafts. Status: live [Use this template](/studio/video/templates/record-room) ## Poem One poem becomes a branded 9:16 video, a carousel and a text draft. Your words stay verbatim. What you bring: A poem or short piece of writing. What you get: A 9:16 video, a carousel and a text post, as drafts. Not a word is changed. Status: live [Use this template](/studio/video/templates/poem) ## Segment ad One of your audiences becomes a 9:16 ad: hook, who it is for, your offer, your proof and a call to action, in your own words. What you bring: One audience segment from your brand, plus your offer. What you get: A 9:16 ad video and its copy, as a draft. Status: live [Use this template](/studio/video/templates/segment-ad) ## Weekly offer campaign A campaign laid out a week at a time: your real offers and prices, a post calendar across your channels, frames on every image, and your approval on each post. The shape of the All That Technology holiday campaign. What you bring: Your offers with prices, the dates, and the channels you post on. What you get: A week-by-week calendar of drafts, ready for you to approve and schedule. Status: live [Use this template](/campaigns/new) ## Alternate realities (parody) A "what if" satire video authored in Chat with HyperFrames. Every frame carries the PARODY · AI label, burned in. What you bring: A premise: "what if this happened instead?" What you get: A labelled parody video draft, screened before it renders. Status: live [Use this template](/create/chat?prompt=Make%20an%20alternate-reality%20parody%20video%3A%20) ## Film Study A coaching breakdown: your clip, telestrator marks, a drill tag, three coaching points and an end card. What you bring: One game or practice clip and your coaching points. What you get: A 9:16 breakdown video with your marks and points. Status: coming_soon --- Source: https://flayr.social/help # Flayr help center - [Getting started](/help/features/getting-started.md) - [Chat](/help/features/chat.md) - [Hook Studio](/help/features/hook-studio.md) - [Brand Intelligence](/help/features/brand-intelligence.md) - [Connect social accounts](/help/features/connect-accounts.md) - [Embers](/help/features/embers.md) - [Post Studio](/help/features/post-studio.md) - [Video creator](/help/features/video-creator.md) - [Voice studio](/help/features/voice-studio.md) - [Library](/help/features/library.md) - [Review and approvals](/help/features/review-and-approvals.md) - [Scheduling and the calendar](/help/features/scheduling.md) - [Ads](/help/features/ads.md) - [Workflows](/help/features/workflows.md) - [Analytics and insights](/help/features/analytics.md) - [Inbox](/help/features/inbox.md) - [Organizations and teams](/help/features/organizations-and-teams.md) - [Client workspaces](/help/features/client-workspaces.md) - [API, webhooks and MCP](/help/features/developer-api.md) - [Campaign builder](/help/features/campaign-builder.md) - [Character Studio](/help/features/character-studio.md) - [Campaigns](/help/features/campaigns.md) - [Where to find Connections](/help/features/find-connections.md) - [Connect over MCP](/help/features/connect-mcp.md) - [Connect your AI agent](/help/features/connect-ai-agent.md) - [Use the API](/help/features/use-the-api.md) - [flayr in two minutes: chat, studio, calendar, queues, workflows](/help/how-to/flayr-01-overview.md) - [Pull your Opus Clip clips straight into flayr](/help/how-to/flayr-02-opus-clip-integration.md) - [I drag in a print, flayr posts one every day](/help/how-to/flayr-03-print-shop-daily-queue.md) - [Automating cross-posting with flayr workflows (quick walkthrough)](/help/how-to/flayr-04-workflows-light.md) - [Scheduling in flayr: drag, drop, and let the queue run](/help/how-to/flayr-05-scheduling.md) - [Clone your voice in flayr's Voice Studio](/help/how-to/flayr-06-voice-cloning.md) - [Ads 1: set up your ad accounts](/help/how-to/flayr-07-ad-accounts-setup.md) - [Ads 2: build a campaign that starts paused](/help/how-to/flayr-08-paused-campaign-build.md) - [Ads 3: comment-to-get, reply automatically to a keyword](/help/how-to/flayr-09-comment-to-get.md) - [Ads 4: test your hooks](/help/how-to/flayr-10-hook-testing.md) - [Ads 5: the funnel, from ad to comment to customer](/help/how-to/flayr-11-the-funnel.md) - [Ads 6: A/B test your ads](/help/how-to/flayr-12-ab-testing.md) - [Ads 7: real results](/help/how-to/flayr-13-real-results.md) - [Templates: start from Record Room, Poem, a segment ad or a weekly campaign](/help/how-to/flayr-14-templates-walkthrough.md) - [Post to every platform at once, then see what's working](/help/how-to/flayr-15-post-everywhere.md) - [Run many accounts from one place](/help/how-to/flayr-16-many-accounts.md) - [Build a campaign: a sale or launch, planned and drafted for you](/help/how-to/flayr-17-campaign-builder.md) - [Connect your store](/help/how-to/start-connect-store.md) - [Bring in your products](/help/how-to/start-products.md) - [Set up your brand](/help/how-to/start-brand-setup.md) - [Connect your social accounts](/help/how-to/start-connect-accounts.md) - [Write one post and send it](/help/how-to/start-first-post.md) - [Add your own photo or video](/help/how-to/start-own-media.md) - [Schedule a post and see your calendar](/help/how-to/start-schedule.md) - [Approve posts before they go out](/help/how-to/start-approvals.md) - [Make a picture for a post](/help/how-to/start-ai-images.md) - [Make a short video](/help/how-to/start-ai-video.md) - [Make a voiceover](/help/how-to/start-voice.md) - [Boost a post](/help/how-to/start-ads-boost.md) - [Answer comments in one place](/help/how-to/start-inbox.md) - [Read your numbers](/help/how-to/start-analytics.md) - [From your store to your Black Friday and Cyber Monday campaign](/help/how-to/flayr-32-commerce-tutorial.md) - [Automate a weekly progress report in flayr](/help/how-to/flayr-33-weekly-progress-report.md) - [Testimonials](/help/testimonials.md) - [Submit a tutorial video](/help/submit.md) - [Templates](/help/templates.md) --- Source: https://flayr.social/help/features # Flayr help center - [Getting started](/help/features/getting-started.md) - [Chat](/help/features/chat.md) - [Hook Studio](/help/features/hook-studio.md) - [Brand Intelligence](/help/features/brand-intelligence.md) - [Connect social accounts](/help/features/connect-accounts.md) - [Embers](/help/features/embers.md) - [Post Studio](/help/features/post-studio.md) - [Video creator](/help/features/video-creator.md) - [Voice studio](/help/features/voice-studio.md) - [Library](/help/features/library.md) - [Review and approvals](/help/features/review-and-approvals.md) - [Scheduling and the calendar](/help/features/scheduling.md) - [Ads](/help/features/ads.md) - [Workflows](/help/features/workflows.md) - [Analytics and insights](/help/features/analytics.md) - [Inbox](/help/features/inbox.md) - [Organizations and teams](/help/features/organizations-and-teams.md) - [Client workspaces](/help/features/client-workspaces.md) - [API, webhooks and MCP](/help/features/developer-api.md) - [Campaign builder](/help/features/campaign-builder.md) - [Character Studio](/help/features/character-studio.md) - [Campaigns](/help/features/campaigns.md) - [Where to find Connections](/help/features/find-connections.md) - [Connect over MCP](/help/features/connect-mcp.md) - [Connect your AI agent](/help/features/connect-ai-agent.md) - [Use the API](/help/features/use-the-api.md) --- Source: https://flayr.social/help/how-to # Flayr help center - [flayr in two minutes: chat, studio, calendar, queues, workflows](/help/how-to/flayr-01-overview.md) - [Pull your Opus Clip clips straight into flayr](/help/how-to/flayr-02-opus-clip-integration.md) - [I drag in a print, flayr posts one every day](/help/how-to/flayr-03-print-shop-daily-queue.md) - [Automating cross-posting with flayr workflows (quick walkthrough)](/help/how-to/flayr-04-workflows-light.md) - [Scheduling in flayr: drag, drop, and let the queue run](/help/how-to/flayr-05-scheduling.md) - [Clone your voice in flayr's Voice Studio](/help/how-to/flayr-06-voice-cloning.md) - [Ads 1: set up your ad accounts](/help/how-to/flayr-07-ad-accounts-setup.md) - [Ads 2: build a campaign that starts paused](/help/how-to/flayr-08-paused-campaign-build.md) - [Ads 3: comment-to-get, reply automatically to a keyword](/help/how-to/flayr-09-comment-to-get.md) - [Ads 4: test your hooks](/help/how-to/flayr-10-hook-testing.md) - [Ads 5: the funnel, from ad to comment to customer](/help/how-to/flayr-11-the-funnel.md) - [Ads 6: A/B test your ads](/help/how-to/flayr-12-ab-testing.md) - [Ads 7: real results](/help/how-to/flayr-13-real-results.md) - [Templates: start from Record Room, Poem, a segment ad or a weekly campaign](/help/how-to/flayr-14-templates-walkthrough.md) - [Post to every platform at once, then see what's working](/help/how-to/flayr-15-post-everywhere.md) - [Run many accounts from one place](/help/how-to/flayr-16-many-accounts.md) - [Build a campaign: a sale or launch, planned and drafted for you](/help/how-to/flayr-17-campaign-builder.md) - [Connect your store](/help/how-to/start-connect-store.md) - [Bring in your products](/help/how-to/start-products.md) - [Set up your brand](/help/how-to/start-brand-setup.md) - [Connect your social accounts](/help/how-to/start-connect-accounts.md) - [Write one post and send it](/help/how-to/start-first-post.md) - [Add your own photo or video](/help/how-to/start-own-media.md) - [Schedule a post and see your calendar](/help/how-to/start-schedule.md) - [Approve posts before they go out](/help/how-to/start-approvals.md) - [Make a picture for a post](/help/how-to/start-ai-images.md) - [Make a short video](/help/how-to/start-ai-video.md) - [Make a voiceover](/help/how-to/start-voice.md) - [Boost a post](/help/how-to/start-ads-boost.md) - [Answer comments in one place](/help/how-to/start-inbox.md) - [Read your numbers](/help/how-to/start-analytics.md) - [From your store to your Black Friday and Cyber Monday campaign](/help/how-to/flayr-32-commerce-tutorial.md) - [Automate a weekly progress report in flayr](/help/how-to/flayr-33-weekly-progress-report.md)