flayr

[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. 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`. (Wraps POST /api/v2/accounts/{id}/refresh.)

[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. Confirm with the user before approving. Needs the `publish` scope (or admin) on the Agency plan or higher. (Wraps POST /api/v2/automations/actions/{id}.)

[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:<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. (Wraps POST /api/v2/posts/{id}/comments.)

[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. Use `contentIds`, or `items` for a per-item YouTube title or platforms. 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. (Wraps POST /api/v2/queues/{id}/items.)

[read-only] The brand's ad account with its currency, spend limit, balance (minor units) and readiness. (Wraps GET /api/v2/ads/accounts.)

[read-only] The brand's published posts ranked for a boost (reach, engagement rate, link clicks, recency), with 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. (Wraps GET /api/v2/ads/boost-candidates.)

[read-only] One ad campaign by its Flayr id, with its ad sets and ads. (Wraps GET /api/v2/ads/campaigns/{id}.)

[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). It cannot resume or activate a campaign; that is done in the Flayr app. Confirm with the user first. (Wraps POST /api/v2/ads/campaigns/{id}/pause.)

[read-only] 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. (Wraps GET /api/v2/ads/campaigns.)

[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. (Wraps GET /api/v2/ads/insights.)

[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. Owners and admins of the brand only. A record only: it never creates, turns on or funds an ad. (Wraps PATCH /api/v2/ads/offers/{claimId}.)

[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. Read-only. (Wraps GET /api/v2/ads/offers.)

[read-only] Whether each connected network and ad account can run ads, and what to fix first. (Wraps GET /api/v2/ads/readiness.)

[writes flayr data · `write` scope] 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. (Wraps POST /api/v2/frames/apply.)

[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. Charges Embers once per call (refunded when nothing usable comes back). Needs the Pro plan or higher. (Wraps POST /api/v2/hook-studio/bodies/map.)

[read-only] 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. (Wraps GET /api/v2/brands/{id}/business-details.)

[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). 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). (Wraps PATCH /api/v2/brands/{id}/business-details.)

[read-only] 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. (Wraps GET /api/v2/brand/intelligence.)

[writes flayr data · `write` scope] 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. (Wraps PATCH /api/v2/brand/intelligence.)

[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). 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. (Wraps DELETE /api/v2/posts/{id}.)

[read-only] 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. (Wraps POST /api/v2/hook-studio/claims/check.)

[writes flayr data · `write` scope] 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`. (Wraps POST /api/v2/experiments/{id}/close-round.)

[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). 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. (Wraps POST /api/v2/content/{id}/combine.)

[read-only] 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. (Wraps GET /api/v2/analytics/experiments.)

[writes flayr data · `write` scope] 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), per-platform captions (`platformText`), creator `credits`, `labels` and YouTube options. Returns the new `id` — pass it as `contentId` to publish or add_queue_items. (Wraps POST /api/v2/content.)

[writes flayr data · `write` scope] 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. (Wraps POST /api/v2/experiments.)

[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). (Wraps POST /api/v2/frames.)

[writes flayr data · `write` scope] 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. (Wraps POST /api/v2/growth-triggers.)

[PUBLISHES to social accounts · `publish` scope] 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. (Wraps POST /api/v2/queues.)

[PUBLISHES to social accounts · `publish` scope] 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. (Wraps POST /api/v2/automations/reshare-rules.)

[writes flayr data · `write` scope] Creates a reusable format (text template) in a brand. (Wraps POST /api/v2/text-templates.)

[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). Run it before every boost or ad and paste the result. Nothing stored, free. Needs the Pro plan or higher. (Wraps POST /api/v2/cta-check.)

[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). Free. Needs the Pro plan or higher. (Wraps GET /api/v2/hook-studio/cta-settings.)

[writes flayr data · `write` scope] 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. (Wraps PATCH /api/v2/hook-studio/cta-settings.)

[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). Nothing here creates or runs an ad. Free. Needs the Pro plan or higher. (Wraps POST /api/v2/hook-studio/ctas.)

[writes flayr data · `write` scope] 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. (Wraps POST /api/v2/hook-studio/ctas/generate.)

[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. Free. Needs the Pro plan or higher. (Wraps GET /api/v2/hook-studio/ctas.)

[writes flayr data · `write` scope] 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. (Wraps PATCH /api/v2/hook-studio/ctas.)

[PUBLISHES to social accounts · `publish` scope] Same rules as the dashboard: only the assigned approver 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. (Wraps POST /api/v2/approvals/{id}.)

[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. "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. (Wraps POST /api/v2/campaigns/{id}/review/sections/{sectionId}.)

[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. decision "hold" takes a scheduled post off the platform schedule — needs `review` or `publish`. Agency plan. `id` is a reviewId or a convexPostId. (Wraps POST /api/v2/reviews/{id}.)

[DESTRUCTIVE] 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. (Wraps DELETE /api/v2/content/{id}.)

[DESTRUCTIVE] DESTRUCTIVE: deletes the experiment record (content keeps its labels). Ask the user before calling. (Wraps DELETE /api/v2/experiments/{id}.)

[DESTRUCTIVE] DESTRUCTIVE: deletes a trigger (its logs stay). Ask the user before calling. (Wraps DELETE /api/v2/growth-triggers/{id}.)

[DESTRUCTIVE] 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. (Wraps DELETE /api/v2/queues/{id}.)

[DESTRUCTIVE] DESTRUCTIVE: deletes a format (drafts started from it keep their text). Ask the user before calling. (Wraps DELETE /api/v2/text-templates/{id}.)

[read-only] Engagement overview for the last 7, 30 or 90 days. Pro plan or higher. (Wraps GET /api/v2/analytics.)

[read-only] 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. (Wraps GET /api/v2/campaigns/{id}/review.)

[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. The item's own `status` stays "draft" after publishing — read `posts` to know whether it is live. Use this to confirm a publish landed. (Wraps GET /api/v2/content/{id}.)

[read-only] One experiment: hypothesis, variants, compareKey, window and status. (Wraps GET /api/v2/experiments/{id}.)